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1.1 Before You Begin 
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The AdvaInform User Application Programmers Interface (User API) provides services 
(functions) which let you access the Advant OCS objects. You can use the User API to develop 
applications with 3-GL languages like C and/or C++. The User API contains functions to read 
from, write to and manipulate the Advant OCS objects in other ways. The User API also 
provides services for system message and date and time handling. 


The User API provides two types of services: 
° Object Access Services and 


° Basic Support Services. 


Object Access Services 


Object Access Services are 3-GL programming interfaces for direct interaction with Advant 
OCS objects. 


The Object Access Services let you: 
° Execute operations on objects. 
° Read attributes from objects, on demand, on event, or cyclically. 


° Read type directory service information. 


Basic Support Services 


This is the 3-GL programming interface to the system resources. It covers, for example, 
handling of system messages and date and time. 


This guide is intended for application programmers. To fully understand the contents, you 
should have basic knowledge about the Advant OCS concept and good knowledge in C or C++ 
programming. 


An application program using the User API can be written in C or C++. There are some 
differences though concerning which tools that are available if you write in C or C++. These 
differences are described more in detail in the following chapters. If you want to write your 
program in some other language than C or C++, refer to Section 3.10, Programming in other 
Languages than C and C++. 


The User API contains all the tools required to integrate different software applications. It offers 
the application programmer a well-defined environment for development of portable 
applications. 


The User API also provides application portability between different Advant platforms and 
system versions. New applications developed on a certain platform will have the same access to 
system resources as system applications, thus giving full, yet controlled access to system 
services. 
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Chapter | gives a brief description of the User API. The other chapters describe, step by step, in 
detail, the services and how to use them. The last chapter contains an FAQ (Frequently Asked 
Questions) section answering the most common questions in the area of AdvaInform User API 


programming. 


1.2 How to Use This Book 


1.3 Conventions 


1-2 


Introduction 


You have already started reading Chapter 1. Go on reading! It gives you a brief knowledge 
about what you can do with the User API. 


Chapter 2 describes the installation of AdvaInform User API. 


Parts of Chapter 3 are intended for inexperienced programmers. However, some of the sections 
are of interest also for experienced programmers. 


In Chapter 4, the first section is intended for inexperienced programmers to get started. 


All of the other chapters, plus Appendix A, Status Codes, are intended for programmers on all 


levels. 


Table 1-1 shows the conventions used in this guide: 


Table 1-1. Conventions used in this guide 


Example... 


.. refer to the Advalnform 
User API User’s Guide.. 


enter command cp file .. 


void main() 


IMS Menu 


.. the Station menu .. 


.. select Editor from the 
Station menu .. 


.. the very first time you .. 


Type of information... 


References to other books are written in italics. 


Italics font used instead of a value or name. 
Italics font used to emphasize. 
Program code and commands are written in Courier font. 


The names of window elements (for example, the title in the 
title bar of a window, the label for a field of a dialog box) are 
written in the same font as where they appear in the windows. 


Initial capital letters are used for the name of menus listed in 
the menu bar. 


Initial capital letters are used for the name of menu items. 
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Table 1-1. Conventions used in this guide (Continued) 


Example... 
.. select Station - Editor ... 


.. enter TIC132 into .. 


Type of information... 
Short for select Editor from the Station menu (above). 


In a tutorial, for ex., you may be told to enter a value into a 
field. The value is then written boldfaced. 


Boldface font is also used whenever there is a need to point 
out a certain word or phrase. 


Other conventions: 


In procedures and tutorials for example, output on the screen is written in Courier: 


Entered value is not valid. 


The value must be 0-30. 


User input is written in bold face: 


TIC132 


1.4 Related Documentation 


Enter an object name: 


Table 1-2 lists all documentation related to AdvaInform User API 


Table 1-2. Related Documentation 


Title 


Description 


Advalnform Basic Functions User’s Guide 


Describes how to use all functions included in 
Advalnform Basic Functions. 


Advant Station 500 IMS User’s Guide 


Gives general rules and recommendations for 
application building in IMS. 


Advalnform SQL Applications User’s Guide 


Similar as this guide but for SQL applications. 


Advalnform Object Types Reference Manual 


Description of attributes, connections, commands, 
events and error messages for Advant OCS objects 
possible to access by User API services. 


A Beginner’s Guide to HP-UX 


Included in the Advant Station 500 IMS delivery. 


Basics and Installation Microsoft Windows NT 
Workstation 


Included in the Windows NT delivery. 


C/ANSI C Compiler 


A C-licence is included in Advalnform Basic Functions. 
However, the C manual has to be ordered separately. 
(only IMS 500) 
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Table 1-2. Related Documentation (Continued) 


Title 


Description 


Advant Basic Functions User’s Guide Describes how to use the functions included in the 


Advant basic software on NT. 


AdvaBuild Object Type Builder 


May be of interest for some users, as User API 


Advalnform Object Handling 


services can now be called from a User Object. 


1.5 Release History 


Table 1-3 lists the major milestones in the development of AdvaInform User API. 


Table 1-3. AdvaInform User API release history 


Version 


Description 


1.0 


Initial version. 


1.1 


Improved User API. Object Access Services extended with services 

to retrieve information for object instances and object types from the 
Type Directory. A new service which lets you send several commands 
in one service call is also added. 


1.2 


Improved User API. A new set of services, the DO -REQUEST 
functions, has been added in order to simplify programming and 
improve performance. Now, there are no restrictions on number of 
concurrent subscriptions. 


1.3 


Available on both HP-UX and Windows NT platforms. A new function 
for setting system time added. New functions for configuring time- 
outs and queues, allocate and deallocate memory etc. User API 
services can now be used from User Objects (IMS 500). Also, a User 
API item has been added to the IMS Advalnform menu (IMS 500). 


1.6 Terminology 


Table 1-4 shows a list of terms associated with AdvalInform User API you should be familiar 
with before you go on reading. 


Table 1-4. Terminology 


Term 


Description 


Advant OCS 


Advant Open Control System. 


AS 5xx 


Short for Advant Station 5xx. For example AS 530. 
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Table 1-4. Terminology (Continued) 


Term 


Description 


Attribute 


Describes the public data of the object. The result of an 
application is most commonly stored in attributes. Attributes also 
contain configured public information. Applications (other 
objects) can request the object’s public data through the core 
system, using subscriptions. 


Command 


A command is a request for an action for an object. As a result, 
the object performs the requested action. 


IMS 


Short for Advant Station 500 Series Information Management 
Station. 


Object 


In the Advant OCS concept, a combination of data and associated 
procedures (operations) are represented by objects. Examples of 
objects are: 


- Process objects. For example PIDCON 
- History logs 
- AdvaInform Basic Objects (AI; AO, ... and so on) 


Event 


A general definition of an event in this context can be expressed 
as: Something that, in some way, changes the status of an object 
(for a definition of object, see above). 


Process Supervision 


IMS system function used to define processes which shall be 
started/supervised when IMS is started. 


System Messages 


IMS system function which handles system messages. 
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1.7 Overview of the User API Environment 


User Application Program 


va Advalnform User API ‘Ne 


Basic Object 
Support Access 
Services Services 


Basic System 


Figure 1-1. AdvaInform User API overview 


The Core System provides communication services for system and user applications. All nodes 
in an Advant OCS communicate with each other through the Core System. 


UXBase contains, for example, functions for communication between User API and the Core 
System, supervision of processes and time synchronization between different Advant OCS 


nodes. 


The Type Directory is a place holder for Advant OCS object type descriptions. To be able to 
access an object using a User API service, a description of the object type has to be included in 
the Type Directory. See Advant Station 500 Series IMS Users’ Guide (IMS) or Advant Basic 


Functions User’s Guide. 
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1.8 Alternative Application Development Tools 


There are other tools available for application building in Advant stations than the User API. 
For example, you can use: 


° SQL services (including AdvaInform SQL Connect and AdvaInform SQL Connect 
Programming) (only IMS 500) Refer to the Advalnform SQL*Connect User’s Guide and 
the AdvaInform SQL*Connect Programming User’s Guidefor more information. 


° AdvaBuild Object Type Builder (only IMS 500) 
Read more about this in the AdvaBuild Object Type Builder. 


° AdvalInform Calculations (only IMS 500 - Master) 
Read more about this in the Advalnform Calculations User's Guide. 


Refer to the Advant Station 500 IMS User’s Guide for a detailed description of the different 
available alternatives for application building. 
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Chapter 2 Installation 


2.1 General 


2.1.1 HP-UX 


The User API is included in the Advalnform Basic Functions. This means that no separate 
installation is required. 


2.1.2 Window NT 


See the Advant Basic Functions User’s Guide for intallation instructions. 
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Chapter 3 Developing Programs with User API 


3.1 Users 


User API applications can be developed by Advant users of category Engineer. Beside this, 
there are no additional restrictions on user category except for the bciSet LocalTime 
function which can be used only by users of category System. 


Ask your system manager or read the Advant Station 500 Series IMS Users’ Guide if you need a 
user of a certain category. 


3.2 Working Directory 


Your working directory is where you edit and store your program source files. It can for example 
be a sub-directory to your home directory. Use the UNIX command mkdir to create a sub- 
directory. 


To use the Make files for compile and link (see Section 3.3.1.2, Make Files (HP-UX) or Section 
3.3.2.3, Make Files (NT)) included in the delivery, you do not have to create any sub-directories 
to your working directory. However, to keep track of all types of files you use while developing 
your application, it is recommended that you modify the Make files, so that they do not store all 
files in one directory. Otherwise, you will run into problems when trying to identify which files 
are which. A commonly used directory structure in UNIX environments is (could also be used 
in NT environment): 


° sre - source and object files 

° include - header (include) files 
° etc - start-up scripts 

° bin - executable files 

° lib - libraries 


° doc - documentation. 


NOTE 


Before you start creating this structure, check whether there are any local 
rules/recommendations for this where you work. 


3.3 Application Development Tools 


3.3.1 HP-UX Environment 


3.3.1.1 Editor 
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Available editors in HP-UX are, for example, vi and dt-pad. 
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Maybe you already have some favorite editor? In that case, use that one. If not, you can use the 
editor set up as default in IMS. You bring up that editor by selecting Editor from the Station 
menu in the IMS menu. 


Note that the IMS default editor can be changed! Ask your system manager or consult the 
Advant Station 500 Series IMS User’s Guide for details. 


3.3.1.2 Make Files 


Make files keep track of which modules that have to be compiled/linked and which that do not 
have to be recompiled/relinked. This is done by comparing the date and time of the source and 
binary files. 


In the /opt /advant/UserAPI/examples directory, there is a User API make tool called 
apiMake. It consists of two files, one shell script, apiMake, and one make file, 
apiMakefile. Copy those files to your working directory. 


To use the Make feature, enter the following command: 
S$ apiMake application name 


An application program using the User API can be written in C or C++. The apiMake tool only 
handles C applications though. C applications must execute the _main() function as early as 

possible in the main () scope. The __main () function executes all C++ constructors (the User 
API is implemented in C++). 


C++ applications can be compiled and linked with a C++ example make file stored in the 
/opt/advant/UserAPI/examples directory. Edit the apiMakefile.cc file and 
change the APIPROG to your application name and enter the command: 


$ make -f apiMakefile.CC 


3.3.1.3 Trace and Debug 


You can trace the execution of your User API application by setting the BCI_TRACE system 
variable in the same shell as the application is started. 


The trace level can be set from 0 (no trace) to 10 (max trace). 
Example: 


S$ export BCI_TRACE=6 


The trace can also be turned on and off from within the application with a function named 
bciSetTrace(int traceValue). 


Example: 
/* Turn on trace */ 


bciSetTrace (6); 


/* Turn off trace */ 


bciSetTrace (0); 
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This C-function can be used if only a part of the application is to be traced. The BCI_TRACE 
variable can only be changed prior to start of the application. 


You can also use the xdb debugger to debug your User API application. It is a source level 
debugger for C, C++, HP FORTRAN and HP Pascal programs. It provides a controlled 
environment for their execution. The HP-UX Symbolic Debugger User’s Guide provides a 
comprehensive description of xdb. You can also enter the command 


$ man xdb 


for a brief description of the command and its parameters. 


NOTE 
The User API libraries can not be debugged by xdb though. 


A couple of other tools - not included in AdvaInform Basic Functions though - are available on 
the market: 


° Glance (included in the IMS Media Kit) 
For performance measurement. 


° Purify 
For detection of memory leakage. 


3.3.2 Windows NT Environment 


3.3.2.1 Development environment 


3.3.2.2 Editor 


3.3.2.3 Make Files 
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AdvaInform UserAPI on NT requires that the user has a software development license, for 
example Microsoft Visual C++ or similar. Otherwise, no application can be built. 


There are a number of available editors in Windows. Chose your favorite editor. 


Make files keep track of which modules that have to be compiled/linked and which that do not 
have to be recompiled/relinked. This is done by comparing the date and time of the source and 
binary files. 


In the Sproductsroot%\UserAPI\examples directory, there is a User API make tool 
called apiMake. It consists of two files, one shell script, apiMake. bat, and one make file, 
apiMakefile.mak. Copy those files to your working directory. 
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To use the Make feature, enter the following command (in a command prompt window): 
> apiMake application name <file extension> 


An application program using the User API can be written in C or C++. The NT apiMake tool 
handles both, but you must add the file extension if the file is not a C program or ends with .C. 
For example, a C++ program called myappl.cpp is compiled and linked with the apiMake tool 
as: 


> apiMake myappl cpp 


3.3.2.4 Trace and Debug 


3.3.2.5 Other tools 
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You can trace the execution of your User API application by setting the BCI_TRACE 
environment variable in the same console window as the application is started. 


The trace level can be set from 0 (no trace) to 10 (max trace). 
Example: 


> set BCI_TRACE=6 


The trace can also be tured on and off from within the application with a function named 
bciSetTrace(int traceValue). 


Example: 


/* Turn on trace */ 


bciSetTrace (6); 


/* Turn off trace */ 
bciSetTrace (0); 
This C-function can be used if only a part of the application is to be traced. The BCI_TRACE 


variable can only be changed prior to start of the application. 


NOTE 
The User API libraries can not be debugged. 


Example of tools - not included in AdvaInform UserAPI though - that are available on the 
market: 


° Microsoft Developer Studio Visual C++ 
Software development environment. 


° Purify for Windows NT 
For detection of memory leakage. 


3BSE 011 011R0101 


Aavalntorm® User API User’s Guide 
Section 3.4 Header Files 


3.4 Header Files 


All header files for the AdvaInform User API except for the object type header files are stored in 
the include directory: 


/opt/advant/UserAPI/include (HP-UX) 
Sproductroot%\UserAPI\include (NT) 

You find the object type header files in the following directory: 
/opt/advant/TypeDir/include (HP-UX) 


Sproductroot%\TypeDir\include (NT) 


3.4.1 bciUserAPI.h 


The main User API header file is bciUserAPI -h. It contains declarations of functions, data 
types and constants. 


3.4.2 bsBCl_def.h 


bsBCI_def .h defines component identities to be used when you format and send system 


messages. 

Userl User application text 
FuncStatus Return status text 

ObjStatus Object access status text 
ObjFlag Object access status flag text 
OpStatus Operation status text 


Those Id’s are to be used together with definition files for each component. For example, if you 
want a text from Userl, the user!_bsBCI_def.h also has to be included in the application. 


3.4.3 user1_bsBCl_def.h 


Definition file for NLS text Id’s for the Userl component which can be used to format your own 
NLS messages or to send messages to System Messages: 


Message1_User1_bsBCI %T 
Message2_Userl_bsBCI %D1 
Message3_Userl_bsBCI %T %D1 
Message4_Userl_bsBCI %D1 %T 
Message5_User1_bsBCI %D1 %D2 
Message6_User1_bsBCI %T %D1 %D2 
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Message7_User1_bsBCI 

Message8_Userl_bsBCI 

Message9_User1_bsBCI 

Message10_Userl_bsBCI 
Messagel1_User1_bsBCI 
Message12_Userl_bsBCI 
Message13_Userl_bsBCI 
Messagel4_Userl_bsBCI 
Message15_Userl_bsBCI 
Message16_Userl_bsBCI 
Message17_Userl_bsBCI 
Message18_Userl_bsBCI 
Message19_Userl_bsBCI 
Message20_Userl_bsBCI 
Message21_Userl_bsBCI 
Message22_Userl_bsBCI 
Message23_Userl_bsBCI 


Message24_Userl_bsBCI 


%D1 %T %D2 

%D1 %D2 %T 

Data = %D1 

%TDI=%DI1 

%T DI = %D1, D2 = %D2 

D1 =%D1, %T 

D1 = %D1, %T, D2 = %D2 

D1 =%D1, D2 = %D2, %T 

%T Value = %D1 

%T Valuel = %D1, Value2 = %D2 
%T Value = %D1, Status = %D2 
Status = %D1 

%T Status = %D1 

Status = %D1, %T 

Error = %D1 

%T Error = %D1 

Error = %D1, %T 

%T Error = %D1, Status = %D2 


Example: Assume that we want the ‘Error = %D1’ text in our application: 
#include <bciUserAPI.h> 


#include <bsBCI_def.h> 


#include <userl_bsBCI_err.h> 


char* NLS_ptr; 


NLS_ptr = bciGetMessagesText (Userl, Message21_Userl1_bsBCI); 


printf(“NLS text = %s”, NLS_ptr); 


See Section 3.9, NLS - Native Language Support for more information about NLS texts. 
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3.4.4 omf_<type>.h 


3.5 Libraries 


The TypeDir/include directory contains all object type header files. The application 
program must include the header file for all object types to be accessed. 


The object type header file defines all attributes, operations, events and data types for a specific 
object type. 


Attributes Attribute that can be read for an object, for example Value, Status, Max 
and Min values etc. 


Operations Operations that can be executed on objects, for example Set Value. 

Events Events raised when certain conditions occur, for example Max Value 
exceeded. 

Data Types Local data types used in attributes, operations and events. 


The name of the header file depends on object type (omf_type.h). Example: The AI object type 
header file name is omf£_AI-h. 


All AdvaInform User API functions are stored in one shared/dll library: 
/opt/advant/UserAPI/lib/libbciapi.sl (HP-UX) 


S$productroot%\UserAPI\lib\libbciapi.lib (NT) 


If the bciSet LocalTime function is used, the following libraries must also be included 
(only HP-UX): 


/opt/advant/oracle/lib/osntab.sl 


NOTE 


The application size will grow by approximately 500 kilobytes when linking with 
Oracle libraries (needed if you use the bciSet LocalTime service). 


3.6 Compile and Link 


3.7 Verification 


3BSE 011 011R0101 


To compile and link - use the Make files described in Section 3.3.1.2, Make Files (HP-UX) or 
Section 3.3.2.3, Make Files (NT). 


Verification of a User API program should be carried out the normal way in software 
development - that is, by defining a set of test cases covering both normal, un-normal, and 
extreme usage. 


If you run into problems, that is, the program behaves in an unpredictable way and you can not 
figure out why, you can use the trace and/or debug facilities as described in Section 3.3.1.3, 
Trace and Debug (HP-UX) or Section 3.3.2.4, Trace and Debug (NT) to find out what happens. 
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3.8 Start of Application Programs 


User API applications can be started in a number of ways. For example: 
° Directly (interactively) from a terminal window (HP-UX) or a command prompt (NT). 


° Cyclically, on event or as a result of a request to execute an operation by the coExecutor 
object which is a part of AdvaInform Object Handling 


° By using the IMS Process Supervision (only IMS 500) 
Refer to the Advant Station 500 Series IMS User’s Guide for a description. 


3.9 NLS - Native Language Support 


The User API supports NLS. You can define NLS files of your own, one for each language 
supported by IMS. The default languages are US English, German and Swedish. 


An NLS file consists of unique Id’s connected to texts. Example: 


FuncStatus_bsBCI 

Error-127_FuncStatus_bsBCI 1 bciNOT_SUPPORTED - API internal 
Error-126_FuncStatus_bsBCI bciTIMEOUT - Coomunication service timeout 
Error-125_FuncStatus_bsBCI bciVERSION - API internal 


Error-124_ FuncStatus_bsBCI bciALLOCATION - Could not allocate resource 


oO ® WN 


Error-123_FuncStatus_bsBCI bciREFERENCE - API internal 


These files are located in sub-directories, one for each language, in following directory: 
/opt/advant/UserAPI/lib/nls (HP-UX) 
Sproductroot%\UserAPI\lib\nls (NT) 


See Figure 3-1 below. 


UserAPI/lib/nls 
c german swedish 
userl_bsBCI.def userl_bsBCI.def userl_bsBCI.def 


funcStatus_bsBCI.def funcStatus_bsBCI.def funcStatus_bsBCI.def 
objStatus_bsBCI.def objStatus_bsBCI.def objStatus_bsBCI.def 
objFlag_bsBCI.def objFlag_bsBCI.def objFlag_bsBCI.def 


Figure 3-1. NLS directory structure 
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HP-UX language selection 


Which file to be selected by NLS functions depends on the system variable LANG. This LANG 
variable can be changed from the IMS menu: Click on Session in the menu bar and then select 
Language. 


Each NLS component consists of two files for each language, one . def file, which is editable, 
and one . cat file which is automatically generated. NLS functions use the . cat file to 
translate Id’s to text. The . cat file is generated with the bsGenerate tool from the . def file. 


Example: 


/opt/advant/UXBase/bin/bsGenerate -c user2_bsBCI.def 


Note that the C-directory in Figure 3-1 holds the US English files. 


NT language selection 


Which file to be selected by NLS functions depends on the language of the current thread that is 
using the UserAPI. The language can be specified via the Regional Settings window (Control 
Panel) or directly in the Windows registry or via an API call. 


Each NLS component consists of one input file for each language with file extension .def. 
This file is used to install the message texts which NLS functions uses to translate Id’s to text. 
The message text is generated and installed with the bsMessagelInstall tool from the . def file. 


Example: 


Sproductroot%\BasicServices\bin\bsMessageInstall /file 
user2_bsBCI.def 


3.9.1 Tutorial - Add NLS text 
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You can add your own NLS texts to be used by your User API applications. For example, 
assume you want NLS texts for ‘Hello’ and ‘Goodbye’. 


1. Log in as ocsmgr on HP-UX and as a SYSTEM category user on NT. 


2. Create anew NLS file, user2_bsBCI.def in the C-directory (note that all texts must have a 
unique Id in the file): 


User2_bsBCI 


HELLO _User2_bsBCI 1 Hello 


GOODBYE_User2_bsBCI 2 Goodbye 


3. HP-UX: Generate the cat file: 
/opt/advant/UXBase/bin/bsGenerate -c user2_bsBCI.def 
NT: Install the message file: 


Sproductroot%\BasicServices\bin\bsMessageInstall /file 
user2_bsBCI.def 


3-9 


Advalnform® User API User’s Guide 
Chapter 3 Developing Programs with User API 


4. Copy the user2_bsBCI.def file to the swedish directory and edit the texts: 


User2_bsBCI 


HELLO_User2_bsBCI 1 Hej 


GOODBYE_User2_bsBCI 2 Adj 6 


5. Repeat step 3 for the new file. 
6. Repeat step 4 and 5 for the german version. 


7. Edit the bsBCI.def file and add the new component (note that the component Id must be 
unique in the file): 


bsBCI 

Userl 1 userl_bsBCI.cat 
FuncStatus 10 funcStatus_bsBCI.cat 
Ob jStatus 11 objStatus_bsBCI.cat 
Obj Flag 12 objFlag_bsBCI.cat 
OpStatus 13 opStatus_bsBCI.cat 
User2 20 user2_bsBCI.cat 


8. HP-UX: Regenerate the header file: 
/opt/advant/UXBase/bin/bsGenerate -d bsBCI.def 
NT: Regenerate header file and install new component: 


Sproductroot%\BasicServices\bin\bsMessageInstall /file 
bsBCI.def 
move bsBCI_def.h %productroot%\UserAPITinclude 


The correct native text is now fetched, see Section 6.6, bciGetMessageText and Section 6.7, 
bciFormatMessageText. 


3.10 Programming in other Languages than C and C++ 


Currently, there is an environment for the User API which makes it possible for you to program 
in C or C++. 


To be able to build applications in some other language, for example Pascal, all declarations in 
the supplied header files have to be converted to Pascal syntax. 
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4.1 Creating a simple User API Program 


Below is a tutorial showing the steps needed to create a simple application program based on the 
User APL. It is mainly intended for inexperienced C programmers. 


4.1.1 User/Log in 


First of all you need an Advant user of category ENGINEER. If you do not have such a user, ask 
your system manager to help you. When you have a user, log in to the Advant node. The 
AdvaInform Basic Functions User’s Guide describes how to do that. 


4.1.2 Working Directory 


Create a working directory where you want to build and run your application. For example as a 
subdirectory to your home directory. Do as follows: 


1. Open a User API terminal window. 


HP-UX: Select User API from the AdvaInform menu in the IMS menu bar. The 
environment will then be set up correctly for User API development. 


NT: Start a command prompt window. 
2. To create the sub-directory (testapplication), enter following commands: 
$ cd 
S$ mkdir testapplication 


§ cd testapplication 


4.1.3 Copy/Edit Program 


As the User API program example is included in the product, you can copy it to your working 
directory. To copy the complete example program to your working directory, enter the following 
command (this assumes that you still are in your working directory): 


HP-UX 
S$ cp /opt/advant/UserAPI/examples/appl.c 
NT 


> copy %productroot%\UserAPI\examples\appl.c 


This means that, to carry out this tutorial, you do not have to type in the program code. 
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If you want to type in the program code in order to learn how to use an editor, do as follows: 


HP-UX 
Bring up the IMS default editor: 


1. Click on Station in the IMS menu bar. 


2. Select Editor from the Station pull down menu. This will bring up the editor window in 
Figure 4-1. 


Editor — (unnamed) 


Figure 4-1. The IMS Editor window 


NOTE 


The IMS default editor can be changed! Ask your system manager or consult the 
Advant Station 500 Series IMS User’s Guide. 


NT 


Bring up your favorite editor, or use some of the editors included in NT. For example, WordPad. 
Select WordPad from Start->Programs->Accessories. 


Now you are ready to follow the C-program example. 


This program reads the Value and Status attributes of two object instances, POT_1 and POT_2, 
of type AI (Analog Input). The bciGetAttributes function is used to read the attributes. 


The program is written as a normal C-application, app1.c, with only a main procedure. 


Below is a listing of the program (there are also some explanations, in italics, included to help 
you understand the code). User API service calls are written in bold face. 


4-2 3BSE 011 011R0101 


Advalnform® User API User’s Guide 
Section 4.1.3 Copy/Edit Program 


/opt/advant/UserAPI/examples/appl.c 


AdvaInform UserAPI tutorial application. 


MN + + FF * F 


/* 

* Include files needed in the application 

Ki] 

#include <bciUserAPI.h> 

#include <stdio.h>/* printf */ 

#include <omf_AI.h>/* AI object type definition file */ 
/* 

* Define constants for number of objects and attributes 
*/, 
#define NO_OBJECTS 2 
#define NO_ATTRIBS 2 


/* 
* Define variables 
* / 
char* objectNames [NO_OBJECTS] = {‘“POT_1”, “POT_2”}; 
int attributes [NO_ATTRIBS] = {OMF_ATVALUEID, 
OMF_ATSTATUSID}; 
size_t valueSizes[ NO_ATTRIBS] = {sizeof (Omf_AIVALUE), 
sizeof (Omf_AISTATUS) }; 
/* 
* Main procedure 
7 


void main() 


{ 


int ob jIdx; 
void** values; 
BciStatus result; 


BciObjStatus** objStatus; 


#ifdef __hpux 

/* 

// Tf HP environment: run constructor for C++ as program coded 
EAC 

i 

_main(); 
#endif 


/* 
* Allocate dynamic memory to be used in the UserAPI call 
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a), 
values = bciAllocAttributes (NO_OBJECTS, 
NO_ATTRIBS, 
valueSizes); 
objStatus = bciAllocObjectStatus (NO_OBJECTS) ; 


/* 

* Perform the request 

/) 

result = bciGetAttributes (objectNames, 

NO_OBJECTS, 
attributes, 
NO_ATTRIBS, 
valueSizes, 


values, 
ob jStatus, 
0); 


/* 
* Check function result 
x] 


if (result != bciSUCCESS) 
{ 
printf (“bceiGetAttributes () \n ERROR $d (%s)\n”, result); 
} 

else 


{ 


/* 
* Print object access status and attribute values 
ay 


printf (“Object Name\tAccess Status Code\tSTATUS\tVALUE\n”) ; 


for (objIdx = 0; objIdx < NO_OBJECTS; objIdx+t+) 
{ 
printf (“Ss\t\tSd\t\t\tslu\t%5.2f\n", 
objectNames [objIdx], 
objStatus [objIdx]->codes, 
* ((Omf_AISTATUS*) values [objIdx] [ 
* ((Omf_AIVALUE*) values [objIdx] [0 


1]), 
])); 


/* 

* Deallocate dynamic memory used 

wd 
bciFreeAttributes (NO_OBJECTS, NO_ATTRIBS, values); 
bciFreeObjectStatus (NO_OBJECTS, objStatus) ; 
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/* 
* Finished! 
* / 

} 


4.1.4 Compile and Link 


Copy the default User API make files, (HP-UX: apiMake and apiMakefile, NT: apiMake.bat 
and apiMakefile.mak) to your working directory: 


HP-UX 


S$ cp /opt/advant/UserAPI/examples/apiMake* 


NT 


S$ copy %productroot%\UserAPI\examples\apiMake* 
Then, compile and link your application with the apiMake tool. 
S$ apiMake appl 


This will create an executable with name appl. 


NOTE 


You must have a C/C++ software development environment to build UserAPI 
applications on NT (for example Microsoft Visual C++). 


4.1.5 Run and Verify 


Before you run your program you must create two Al-objects, POT_1 and POT_2. When you 
have done that, start your application program interactively. That is, enter the command 


$ appl 
in the User API terminal/command prompt window you already have on your screen. 


Below you can see the output from the program: 


Object Name Access Status Code STATUS VALUE 


POT_1 at 65605 8.00 
POT_2 1 93 20.00 
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4.2 Function Parameters - General 


4.2.1 Status Codes 


4.2.2 Pointers 


There are two types of status codes in the User API: 
¢ Function return status 


Returned by function calls and reflects only the status of the function call itself, for 
example illegal arguments. 


° Object access status 


Status of each object being accessed. Consists of flags and status codes. The flags are used 
to report information that can coexist with the status code, for example if the attribute 
value has changed since last read. (Do not be confused with the STATUS attribute of an 
object) 


All function return and object status codes are defined in the bciUserAPI .h header file. 


All status codes are described in Appendix A, Status Codes. They can be translated by the User 
API application using NLS. Use the bciGetMessageText function to translate status codes to 
text. Select the correct component from bsBCI_def.h and add an offset (128) to the status code. 
For example, assume that we want to translate the function return status. Use the funcStatus 
constant from bsBCI_def.h and add the offset: 


#include <bciUserAPI.h> 
#include <bsBCI_def.h> 


status = bciObjectTypes(objectNames, 2, objectTypeNames) ; 


printf(“The bciObjectTypes returned %d (%s)”, 
status, 
bciGetMessageText (FuncStatus, 128+status)); 


The same procedure applies for object access status and flag codes. 


Pointers are frequently used as parameters to User API functions. With bciGetAttributes 
for example: 


BciStatus bciGetAttributes (const char** objectNames, 
int objectCount, 
const int* attributes, 
int attributeCount, 
const size_t* valueSizes, 
void*** values, 
BciObjStatus** status, 
int uniqueldentity) ; 
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The arguments can be shown graphically (Figure 4-2). For example when reading five attributes 
from two objects: 


const char** objectNames —py-| ObjectName 1 Subscribed 
ObjectName 2 Data from 
Controller 
const int* attributes _—— Be} AttrID1 | 
Se 
AttrID 2 pb aterPtr 1 Value 1 
AttrID3 |} AttrPtr 2 Value 2 
AttrID4 [| AttrPtr 3 Value 3 
AttrID5 [| 


Value 4 
Value 5 


AttrPtr 4 
AttrPtr 5 


const size_t* valueSizes — pgs! ValSize 1 | 


VEL 
aL 
LAN 


ValSize 2 gs AttrPtr 1 Value 1 
ValSize 3 AtnPir 2 Value 2 

valSized BO |---| 
acted |] AttrPtr 3 Value 3 

ValSize 5 a 
AttrPtr 4 Value 4 
5 pokskeok ; AttrPtr 5 Value 5 
void values =—_____ ObjVal 1 


ObjVal 2 


BciObjStatus** status 


= Object Type related parameter 


= Object Instance related parameter 


HE = Object Access Status related parameter 


Figure 4-2. Pointer structure 


Allocation of memory 
The parameters can be allocated with either malloc or User API services. 


Example with malloc: 


void*** values; 

BciObjStatus** objStatus; 

/* Allocate array of two void** pointers */ 

values = malloc (2*sizeof (void**)); 

/* Allocate array of two BciObjectStatus pointers */ 
objStatus = malloc(2*sizeof (BciObjStatus*) ); 
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/* For each object ... */ 


for (objIdx = 0; objiIdx < 2; objIdxt+t) 


{ 


/* Allocate data area for each objStatus element */ 


objStatus[objIdx] = malloc(sizeof(BciObjStatus) ); 
/* Allocate array of five void* for each values element */ 
values [objIdx] = malloc (5*sizeof (void*)); 


/* For each attribute to this object 


for (attIdx = 0; attIdx < 5; attIdx+t+) 


{ 


AY 


/* Allocate data area for each attribute */ 
values [objIdx] [attIdx] = malloc(attributeSizes[attIdx]); 


} 


The above example with use of User API services: 
void*** 
BciObjStatus** 


values; 
ob jStatus; 


/* No. of objects=2, No. of attributes per object=5 */ 


values = bciAllocAttributes (2, 
5, 


Deallocation of memory 


attributeSizes); 
objStatus = bciAllocObjectStatus (2); 


It’s important to deallocate all allocated memory before exiting the application! 


Example with use of free: 


/* For each of the 2 objects ... */ 


for (objIdx = 0; objIdx < 2; objIdxt+t) 


{ 


/* For each 5 attribute of this object 
for (attIdx = 0; attIdx < 5; attIdx+t+) 


{ 
/* Deallocate attribute data area */ 
free (values [objIdx] [attIdx]); 
} 
/* Deallocate values array */ 
free (values [objIdx]); 
/* Deallocate objStatus element */ 


4-8 


ef 


3BSE 011 011R0101 


Aavalntorm® User API User’s Guide 
Section 4.2.3 Attributes 


free (objStatus [objIdx]); 

} 
/* Deallocate values matrix */ 
free (values); 
/* Deallocate objStatus array */ 
free (objStatus) ; 


The above example with use of User API services: 


bciFreeAttributes(2, 5, values); 
bciFreeObjectStatus(2, ob jStatus); 


4.2.3 Attributes 


The order of attribute Id’s, attribute sizes and attribute values must be kept. For example, if you 
are subscribing for the NAME, STATUS and VALUE attributes for an AI object instance: 


attributes[0] = OMF_AINAMEID; 
attributes[1l] = OMF_AISTATUSID; 
attributes[2] = OMF_AIVALUEID; 
valueSizes[0] = sizeof (Omf_AINAME) ; 
valueSizes[1] = sizeof (Omf_AISTATUS) ; 
valueSizes[2] = sizeof (Omf_AIVALUE) ; 


4.3 Capacity and Performance 


Capacity and performance is described in the Advant Station 500 IMS User’s Guide. You can 
find such information for all options. 
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The Object Access Services support direct interaction with process and system objects. They let 
you execute operations on objects (on demand or cyclically) and to read data from objects (on 
demand, on event, or cyclically). 


To see the advantages with using User API or any of the other application development tools, 
see the Advant Station 500 IMS User’s Guide. 


5.1.1 List of Object Access Services 


Table 5-1. List of Object Access Services 


object type directory 


Object Access Services Summary Example Files 
bciResolveObjects Resolves object instances bciResolveObjectsEx 
bciObjTypeAttributes Gets object type attributes from the | bciDataTypeElementsEx 
object type directory 

bciObjTypeOperations Gets operations for object type from | bciDataTypeElementsEx 
the object type directory 

bciObjTypeEvents Gets events for object type from the | bciDataTypeElementsEx 


bciDataTypeElements 


Gets information on elements from 
the object type directory 


bciDataTypeElementsEx 


bciGetObjectInformation 


Gets the Object Identity, OID, for 
object instances 


bciGetObjectInformationEx 


identifier and object names 


bciGetCapStatus Returns capability access status from | bciGetAttributesCyclicEx 
the latest request. 
bciCreate Request Creates a unique identifier to identify | bciDoRequestEx 
one or many service requests 
bciDoRequest Performs requests identified by a bciDoRequestEx 
unique identifier 
bciDeleteRequest Deletes unique identifier and all bciDoRequestEx 
requests connected with that 
identifier 
bciCancelRequest Deletes requests identified by unique | bciDoRequestEx 
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Table 5-1. List of Object Access Services (Continued) 


bciGetAttributes 


Gets attribute values once 


bciGetAttributesEx 


bciGetAttributesWithInit 


Gets attribute values once with 
initialize operation 


bciGetAttributes WithInitEx 


bciGetAttributesCyclic 


Gets attribute values cyclically 


bciGetAttributesCyclicEx 


bciGetAttributesCyclicWithInit 


Gets attribute values cyclically with 
initialize operation 


bciGetAttributesCyclicWithInitEx 


bciGetAttributesOnEvent 


Gets attribute values on specified 
event 


bciGetAttributesOnEventEx 


bciGetAttributesOnEventWithInit 


Gets attribute values on specified 
event with initialize operation 


bciGetAttributesOnEventWithInitEx 


bciGetData 


Gets subscription data 


bciGetAttributesCyclicEx 


bciExitFromGetData 


Exit from the bciGetData state 


bciGetAttributesOnEventWithInitEx 


bciCancelGet 


Cancel permanent data subscriptions 
from one or several object instances 


bciGetAttributesCyclicEx 


bciCancelAll Cancel all data subscriptions towards | bciGetAttributesOnEventEx 
object instances 

bciExecOperations Execute a single operation on several | bciExecOperationsEx 
object instances 

bciExecOperationsCyclic Execute a single operation cyclically | bciExecOpCyclicEx 
on several object instances 

bciAllocAttributes Allocates memory for attribute data | bciGetAttributesEx 

bciAllocOperations Allocates memory for operation data | bciExecOperationsEx 


bciAllocEvents 


Allocates memory for event data 


bciGetAttributesOnEventEx 


bciAllocObjectStatus 


Allocates memory for object status 


bciGetAttributesEx 


bciAllocObjectTypeNames 


Allocates memory for object type 
names 


bciDataTypeElementsEx 


bciAllocObjectIDs 


Allocates memory for object id’s 


bciGetObjectInformationEx 


bciFreeAttributes 


Releases attribute data memory 


bciGetAttributesEx 


bciFreeOperations 


Releases operation data memory 


bciExecOperationsEx 


bciFreeEvents 


Releases event data memory 


bciGetAttributesOnEventEx 


bciFreeObjectStatus 


Releases object status memory 


bciGetAttributesEx 


bciFreeObjectTypeNames 


Releases object type name memory 


bciDataTypeElementsEx 


bciFreeObjectIDs 


Releases object id memory 


bciGetObjectInformationEx 
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Table 5-1. List of Object Access Services (Continued) 


bciSetQueueSize 


Sets queue size of incoming bciConfigurationEx 
packages from Advant OCS 


bciSetResolveTimeOut Sets time out for resolving objects bciConfigurationEx 

bciSetWaitTimeOut Sets time out for waiting for demand | bciConfigurationEx 
data 

bciGetConfiguration Returns current values of bciConfigurationEx 


configurable parameters 


5.2 About the Service Descriptions/Examples 


Each of the services in Table 5-1 are described in the following sections. All the examples listed 
are included in AdvaInform UserAPI. HP-UX path plus file name is written in the very first 
comment line of each example listing: 


/opt/advant /UserAPI/examples/file name 


In some cases a service has no example of its own. In those cases you are referred to an example 
of another service where the service at hand is used. 


The service(s) which is currently described is marked in boldface in the program listing. 


5.3 bciResolveObjects 


5.3.1 Description 
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This service resolves a number of object instances in the core system. 


Synopsis 
#include <bciUserAPI.h> 


BciStatus bciResolveObjects ( 


const char** objectNames, 

int objectCount, 
char** objectTypeNames, 
BciObjStatus** status); 
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Parameters 

Par. Name: Direction: Description: 

objectNames in Array with object instance names. 

objectCount in Number of object instance names in the objectNames 
array. 

objectTypeNames in/out Array of object type names, one per object. 

Status out Array of pointers to object statuses, one per object. 

Description 


The bciResolveObjects function resolves object instances in the core system. An array of 
object instances of different types can be resolved at one time. The function can be used for 
those object instances which require the object type as key for object resolution, e.g MOD 300 
TCL object instances associated with units. It can also be used to determine the object type for 
an instance. 


The object ypeNames array must be allocated by the caller. 

If the type is unknown the array must be filled with empty strings and the function will fill the 
array with the type for each resolved object instance. Otherwise, if the type is known, fill the 
array with the type for each object. 


NOTE 


The max length of a object type name is defined in an UserAPI constant, 
bciMAX_TYPE_LENGTH 


Return Values 


bciSUCCESS Successful completion 
bciAPI_EXE_ FAILED System function has failed 
bciAPI_RESOURCE_LACK Could not allocate memory 


bciALLOCATION Could not allocate OMF resource 
beiILLEGAL_NAME Illegal characters in all given symbol names 
bciNO_PRIVILEGE Privilege not allowed 

bciTYPE Illegal object type name 


See Section A.3, Status Codes from Object Access Services for translation of the object status 
code. 
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5.3.2 Example 
/* 


* /opt/advant/UserAPI/examples/bciResolveObjectsEx.c 


* 


* Resolving two objects, 


*/ 


#include <stdio.h> 


#include <stdlib.h> /* exit 
#include <bciUserAPI.h> /* UserAPI include file */ 


#define NO_OBJECTS 2 


void main 
{ 


int 


() 


ob jIdx; 


BciStatus result; 
BciObjStatus** ob jStatus; 


Const char* 


char* 


ob jTypeName [NO_OBJI 


#ifdef __hpux 


_main(); 


#endif 


+7 


SC5_2_UNIT1.IMS_BIG1 and SC5_2_UNIT1.IMS_BIG2 


/* printf */ 


objNames[] = {"SC5_2_UNIT1.IMS_BIG1", 


"SC5_2_UNIT1.IMS_BIG2"}; 


ECTS] = {"TCL_AR_UNIT_VAR", 


"TCL_AR_UNIT_VAR"}; 


/* Run constructors for C++ as program coded in C */ 


objStatus = beciAllocObjectStatus (NO_OBJECTS) ; 
= bciResolveObjects (objNames, NO_OBJECTS, 
(char**) &objTypeName, objStatus) ; 


result 


if (result != bciSUCCESS) 


{ 


printf ("bciResolveObjects 


exit(1); 


} 


for (ob 


{ 
if 


else 


printf("%Ss resolved\n", 


jIdx = 0; objIdx < NO_OBJ 


(objStatus [objIdx]->codes 


objNames [objIdx], 


bciFreeObjectStatus (NO_OBJECTS, 


} 


ERROR %d\n", result); 


ECTS; ob jiIdx++) 


bciSUCCESS) 


printf("%s Object Status %d\n", 


ob jStatus [objIdx]->codes) ; 


ob jNames [objIdx]); 


ob jStatus); 


3BSE 011 011R0101 


5-5 


Advalnform® User API User’s Guide 
Chapter 5 Object Access Services 


5.4 bciObjTypeAttributes 


5.4.1 Description 


This service returns the type directory information for the attributes of a named object type. 


Synopsis 
#include <bciUserAPI.h> 


BciStatus bciObjTypeAttributes ( 


const char* objectTypeName, 
int* attributeCount, 
char*** attributeNames, 
size_t** attributeSizes, 
BciDataType** attributeTypes, 


BciDataTypeIndex** attrTypeIndexes) ; 


Parameters 
Par. Name: Direction: Description: 
objectTypeName in Object type name to get attribute information for 
attributeCount out Number of attributes in the attribute arrays returned 
attributeNames out Pointer to array of attribute names 
attributeSizes out Pointer to array of attribute data type sizes 
attributeTypes out Pointer to array of attribute data type identifiers 
attrTypelIndexes out Pointer to array of attribute data type indexes. Can be used 
as input to bciDataTypeElements (see Section 5.7, 
bciDataTypeElements). 
Description 


The bciObjTypeAttributes function retrieves the type directory information for the attributes 
of the object type specified in the objectTypeName parameter. The attributeCount parameter is 
the number of attributes for the object type and defines the size of the different output arrays. 
All of the output arrays are allocated by the bciObjTypeAttributes function, and will be 
overwritten by the next call to the function. 


The data type index is a unique identifier for a data type and can only be explored with the 


bciDataTypeElements function. 


NOTE 


If the output arrays information content should persist, it must be copied into the 
application memory, before the next call to the function. 


5-6 3BSE 011 011R0101 


5.4.2 Example 


Advalnform® User API User’s Guide 
Section 5.4.2 Example 


Return Values 


bciSUCCESS Successful completion 
bciAPI_RESOURCE_LACK Could not allocate memory 
bciTYPE Illegal object type name 


See Section 5.7, bciDataTypeElements. 


5.5 bciObjTypeOperations 


5.5.1 Description 
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This services returns the type directory information for the operations of a named object type. 


Synopsis 
#include <bciUserAPI.h> 


BciStatus bciObjTypeOperations ( 


const char* objectTypeName, 
int* operationCount, 
char*** operationNames, 
size_t** operationSizes, 


BciDataTypeIndex** operTypeIndexes) ; 


Parameters 

Par. Name: Direction: Description: 

objectTypeName in Object type name to get operation information for 

operationCount out Number of attributes in the operation arrays returned 

operationNames out Pointer to array of operation names 

operationSizes out Pointer to array of operation data type sizes 

operTypelndexes out Pointer to array of operation data type indexes. Can be 
used as input to bciDataTypeElements (see Section 5.7, 
bciDataTypeElements). 

Description 


The bciObjTypeOperations function retrieves the type directory information for the operations 
for the object type specified in the objectTypeName parameter. The operationCount parameter is 
the number of operations for the object type and defines the size of the different output arrays. 
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5.5.2 Example 


All of the output arrays are allocated by the bciObjTypeOperations function, and will be 
overwritten by the next call to the function. 


The data type index is a unique identifier for a data type and can only be explored with the 
bciDataTypeElements function. 


NOTE 


If the output arrays information content should persist, it must be copied into the 
application memory, before the next call to the function. 


Return Values 


bciSUCCESS Successful completion 
bciAPI_RESOURCE_LACK Could not allocate memory 
bciTYPE Illegal object type name 


See Section 5.7, bciDataTypeElements. 


5.6 bciObjTypeEvents 


5.6.1 Description 
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This service returns the type directory information for the events of a named object type. 


Synopsis 
#include <bciUserAPI.h> 


BciStatus bciObjTypeEvents ( 


const char* objectTypeName, 
int* eventCount, 
char*** eventNames, 
size_t** eventSizes, 


BciDataTypeIndex** evTypeIndexes) ; 


Parameters 

Par. Name: Direction: Description: 

objectTypeName in Object type name to get event information for 
eventCount out Number of events in the event arrays returned 
eventNames out Pointer to array of event names 
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eventSizes out Pointer to array of event data type sizes 
evTypelndexes out Pointer to array of event data type indexes. Can be used as 
input to bciDataTypeElements (see Section 5.7, 
bciDataTypeElements). 
Description 


The bciObjTypeEvents function retrieves the type directory information for the events of the 
object type specified in the objectTypeName parameter. The eventCount parameter is the 
number of events for the object type and defines the size of the different output arrays. All of the 


output arrays are allocated by the beiObjTypeEvents function, and will be overwritten by the 
next call to the function. 


The data type index is a unique identifier for a data type and can only be explored with the 
bciDataTypeElements function. 


NOTE 


If the output arrays information content should persist, it must be copied into the 
application memory, before the next call to the function. 


Return Values 


bciSUCCESS Successful completion 
bciAPI_RESOURCE_LACK Could not allocate memory 
bciTYPE Illegal object type name 


See Section 5.7, bciDataTypeElements. 
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5.7 bciDataTypeElements 


5.7.1 Description 


This service returns the type directory information for the elements in a constructed data type 
for a specified data type. 


Synopsis 
#include <bciUserAPI.h> 


BciStatus bciDataTypeElements ( 
BciDataTypeIndex typeIndex, 


int* elementCount, 
char*** elementNames, 
size_t** elementOffsets, 
size_t** elementSizes, 
BciDataType** elementTypes, 
BciDirection** elemDirections, 


BciDataTypeIndex** elemTypeIndexes) ; 


Parameters 
Par. Name: Direction: Description: 
typelndex in Data type index for attribute, operation or event. 
elementCount out Number of elements in the element arrays returned 
elementNames out Pointer to array of element names 
elementOffsets out Pointer to array of element data offsets within data 
structure 
elementSizes out Pointer to array of element data type sizes 
elementTypes out Pointer to array of element data type identifiers 
elemDirections out Pointer to array of element data directions 
elemTypelndexes out Pointer to array of element data type indexes. One of the 
elements in the array can be used as input to this service - 
parameter typelndex. 
Description 


The bciDataTypeElements function retrieves the type directory information for a constructed 
data type’s elements of a given data type index. The data type index is only useable as an 
identifier for a specific data type. The function should only be used together with 
bciObjTypeAttributes, bciObjTypeOperations and bciObjTypeEvents functions which 
returns a data type index for each data type. 
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5.7.2 Example 


The elementCount parameter is the number of elements for the data type and defines the size of 
the different output arrays. All of the output arrays are allocated by the bciDataTypeElements 
function, and will be overwritten by the next call to the function. 


NOTE 


If the output arrays information content should persist, it must be copied into the 
application memory, before the next call to the function. 


Return Values 


bciSUCCESS 
bciAPI_LRESOURCE_LACK 
bciTYPE 


Successful completion 
Could not allocate memory 


Illegal object type name 


/* 


/opt/advant /UserAPI/examples/bciDataTypeElementsEx.c 


* Resolving two objects, AI1 and DI1. 
Show all Attributes, Operations and Events of the object type. 
*/ 


#include <stdio.h> /* printf */ 
#include <stdlib.h> /* exit */ 
#include <string.h> /* strcepy, strcat*/ 


#include <bciUserAPI.h> /* UserAPI include file */ 


#define NO_OBJECTS 2 
void printDataType (int depth, 
BciDataType type, 
BciDataTypeIndex typelIndex) 
{ 
int elmIdx; 
int elementCount; 
char indent [10] = “%; 
char** elementNames; 
size_t* elementOffsets; 
size_t* elementSizes; 
BciStatus result; 
BciDataType* elementTypes; 
BciDirection* elemDirections; 
BciDataTypeIndex* elemTypeIndexes; 
if (type == bciSTRUCT || type == bciUNION || type == bciCOMPOSITION) 


{ 
result = bciDataTypeElements (typeIndex, 
&elementCount, 
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&elementNames, 
&elementOffsets, 
é&elementSizes, 
&elementTypes, 
é&elemDirections, 
&elemTypeIndexes) ; 


if (result != bciSUCCESS) 


printf (“bciDataTypeElements() ERROR %d\n”, result); 
exit(1); 


/* Indent the print out */ 
for (elmIdx = 0; elmIdx < depth; elmIdx++) 
wo); 


strcat (indent, 


for (elmIdx = 0; elmIdx < elementCount; elmIdx++) 


printf (“%s%s\t\t%d\t%d\n", 
indent, 
elementNames [elmIdx], 
element Sizes [elmIdx], 
elementTypes [elmIdx] ); 
/* Recursive print if complex element */ 
printDataType(depth+1, 
elementTypes[elmIdx], 
elemTypeIndexes [elmIdx]) ; 


void main() 


int count; 

int ob jIdx; 

int elmIdx; 

const char* objNames[] = {“AI1”, “DI1"}; 
char** objTypeNames; 
char** names; 
size_t* sizes; 
BciStatus result; 
BciDataType* types; 
BciDataTypeIndex* typeIndexes; 
BciObjStatus** objectStatus; 


#ifdef __hpux 
_main(); /* Run constructor for C++ as program coded in C */ 
#endif 


/* Get object type for each object name */ 

objectStatus = bciAllocObjectStatus (NO_OBJECTS) ; 

objTypeNames = bciAllocObjectTypeNames (NO_OBJECTS) ; 

result = bciResolveObjects (objNames, NO_OBJECTS, 
objTypeNames, objectStatus) ; 
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if (result != bciSUCCESS) 


{ 


printf (“bciResolveObjects() ERROR %d\n”, result); 
exit(1); 


} 


for (objIdx = 0; objIdx < NO_OBJECTS; objIdx++) 


{ 


if (objectStatus [objIdx]->codes != bciOBJ_SUCCESS) 
{ 
printf(“%s Not resolved (code = %d)\n"”, 
objNames[objIdx], objectStatus [objIdx]->codes) ; 
} 
else 


{ 
printf(“\n%s resolved as %s\n"”, 
objNames[objIdx], objTypeNames [objIdx]); 
printf (™ \n”); 
/* Print all Attributes for this object type */ 
result = bciObjTypeAttributes (objTypeNames[objlIdx], 
&count, 
é&names, 
&sizes, 
&types, 
&typeIndexes) ; 


if (result != bciSUCCESS) 
{ 
printf (“bciObjTypeAttributes() ERROR %d\n”, result); 
exit(1); 
} 
printf (“\nAttributes\tSize\tType\n”) ; 
printf (™ \n”); 
for(elmIdx = 0; elmIdx < count; elmIdx++) 
{ 
printf (“%Ss\t\tsd\t%d\n", 
names[elmIdx], sizes[elmIdx], types[elmIdx]); 
printDataType(1, types[elmIdx], typeIndexes [elmIdx]); 
} 
/* Print all Operations for this object type */ 
result = bciObjTypeOperations (objTypeNames[objlIdx], 
&count, 
é&names, 
&sizes, 
&typeIndexes) ; 


if (result != bciSUCCESS) 
{ 
printf (“bciObjTypeOperations() ERROR %d\n”, result); 
exit(1); 
} 
printf (“\nOperations\tSize\tType\n”) ; 
printf (™ \n"); 
for (elmIdx = 0; elmIdx < count; elmIdx++) 
{ 
printf (“%s\t\t%d\n”, names[elmIdx], sizes[elmIdx]); 
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printDataType(1, bciCOMPOSITION, typeIndexes[elmIdx] ); 
} 
/* Print all Events for this object type */ 
result = bciObjTypeEvents (objTypeNames [objIdx], 
&count, 
énames, 
&sizes, 
&typeIndexes) ; 
if (result != bciSUCCESS) 
{ 
printf (“bciObjTypeEvents() ERROR %d\n”, result); 
exit(1); 
} 
printf (“\nEvents\t\tSize\tType\n”) ; 
printf (™ \n™); 
for (elmIdx = 0; elmIdx < count; elmIdx++) 
{ 
printf (“%s\t\t%d\n"”, names[elmIdx], sizes[elmIdx]); 
printDataType(1, bciCOMPOSITION, typeIndexes[elmIdx] ); 


} 


bciFreeObjectStatus (NO_OBJECTS, objectStatus); 
bciFreeObjectTypeNames (NO_OBJECTS, objTypeNames) ; 


} 


5.8 bciGetObjectinformation 


5.8.1 Description 


This service returns the Object [Dentity, OID, for object instances. 


Synopsis 
#include <bciUserAPI.h> 


BciStatus bciGetObjectInformation ( 


const char** objectNames, 
int objectCount, 
BciOID** oid, 
BciObjStatus** status); 
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Parameters 
Par. Name: 


objectNames 


objectCount 


oid->byteO 


oid->bytel 


oid->byte2 


oid->byte3 


oid->sequenceNumber 


Status 


Description 


Direction: 


out 


out 


out 


out 


out 


out 
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Description: 
Array with object instance names. 


Number of object instance names in the objectNames 
array. 


Array of first address byte. 

MASTER = 0x00 

MOD DCN = 0x40 

OMF92(MB/DCN) = 0xCO 

OMF93(IP) = first address byte = 80-DF (NOT class A). 


Array of second address byte. 
MASTER = network number 


MOD DCN = device ID 
IP = second address byte. 


Atray of third address byte. 


MASTER = node number 
MOD DCN = subdevice ID 
IP = third address byte. 


Array of fourth address byte. 


MASTER = 0x00 
MOD DCN = OxFF 
IP = fourth address byte. 


Array of unique numbers (per node). One for each object 
instance. 


Atray of pointers to object statuses, one per object. 


The bciGetObjectInformation function retrieves the object identity for one or several object 
instances. This identity, divided in four bytes plus a sequence number, is unique for each object 
instance in the entire Advant OCS. 
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Return Values 


bciSUCCESS Successful completion 
bciAPI_EXE_ FAILED System function has failed 
bciAPI_LRESOURCE_LACK Could not allocate memory 


bciALLOCATION Could not allocate OMF resource 
bceiILLEGAL_NAME Illegal characters in all given symbol names 
bciNO_PRIVILEGE Privilege not allowed 

5.8.2 Example 
/ * 


* /opt/advant/UserAPI/examples/bciGetOb ject InformationEx.c 


* 


* Retrieve OID for two objects, AI1 and DI1 


Re 
#include <stdio.h> /* printf */ 
#include <stdlib.h> /* exit */ 


#include <bciUserAPI.h> /* UserAPI include file */ 


#define NO_OBJECTS 2 


void main() 


{ 


int ob jIdx; 

Berorp** oid: 

BciStatus result; 

BciObjStatus** objStatus; 

const. char* objNames[] = {*AI1”, “DI1"}; 


#ifdef __hpux 
_main(); /* Run constructor for C++ as program coded in C */ 


#endif 


oid = bciAllocObjectIDs (NO_OBJECTS) ; 
objStatus = bceiAllocObjectStatus (NO_OBJECTS) ; 
result = bciObjectInformation (objNames, 

NO_OBJECTS, 

oid, 

ob jStatus) ; 


if (result != bciSUCCESS) 


{ 
printf (“bciObjectInformation ERROR %d\n”, result); 


exit(1); 
} 


for (objIdx = 0; objIdx < NO_OBJECTS; objIdx++) 
{ 


5-16 3BSE 011 011R0101 


Aavalnform® User API User’s Guide 
Section 5.9 bciGetCapStatus 


if (objStatus [objIdx]->codes != bciSUCCESS) 
{ 
printf(“%s Object Status %d\n”, 
objNames[objIdx], ob jStatus[objIdx]->codes) ; 


} 
else 
{ 
printf(“%s OID = %$d.%d.%d.%d.Sd\n"”, 
ob jNames [objIdx], 
oid[objIdx]->byte0d, 


oid[objIdx]->bytel, 
oid[objIdx]->byte2, 
oid[objIdx]->byte3, 
oid[objIdx]->sequenceNumber) ; 


bciFreeObjectIDs (NO_OBJECTS, oid); 
bciFreeObjectStatus (NO_OBJECTS, objStatus); 
} 


5.9 bciGetCapStatus 


5.9.1 Description 


This service returns the access status for each capability, attribute, from the last request. 


Synopsis 
#include <bciUserAPI.h> 


BciStatus bciGetCapStatus ( 


const char* objectName, 
BciObjStatus** status); 
Parameters 
Par. Name: Direction: Description: 
objectName in Object instance name. 
status out Pointer to array of capability statuses. 
Description 


The bciGetCapStatus function returns the access status for each capability (attribute) from the 
last object request. This function can be used if the sum status in the last request was not 
bciOBJ_SUCCESS for any object instance. The status array is allocated and managed by the 
UserAPI, and shall not be deleted by user. 
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NOTE 


This function can only be used with DoRequest, cyclic or on event subscriptions. 


Return Values 


bciSUCCESS Successful completion 
bciNO_ASSOCIATION No subscriptions active 


5.9.2 Example 


See Section 5.16, bciGetAttributesCyclic. 
5.10 bciCreateRequest 


5.10.1 Description 


This service returns a unique integer value to be used within the application. 


Synopsis 
#include <bciUserAPI.h> 


BciStatus bciCreateRequest ( 


int* uniquelIdentity, 
BciBoolean dynamicRequest) ; 
Parameters 
Par. Name: Direction: Description: 
uniqueldentity out A unique integer value which identifies one or many 


demand subscriptions or operation executions. 


dynamicRequest in If set to bciTrue, the input parameters can be changed 
between two bciDoRequest calls. 


Description 


The bciCreateRequest function creates a unique integer value to be used. Requests will be 
saved on the RTA board and just refreshed on a bciDoRequest call when the dynamicRequest is 
false. This means that the dynamicRequest must be set to true if input parameters should be 
changed between two bciDoRequest calls. The performance of the reading/operation will be 
lower but this is partly compensated by a more dynamic execution. To understand the total 
effect, see Section 4.3, Capacity and Performance. 
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Return Values 


bciSUCCESS Successful completion 
bciAPI_EXE_ FATILED System function has failed 
bciALLOCATION Could not allocate OMF resource 
bciNO_PRIVILEGE Privilege not allowed 


5.10.2 Example 


See Section 5.11, bciDoRequestt. 


5.11 bciDoRequest 


5.11.1 Description 


This service performs all actions identified with the unique identity number. 


Synopsis 
#include <bciUserAPI.h> 


BciStatus bciDoRequest ( 


const int uniqueIdentity); 
Parameters 
Par. Name: Direction: Description: 
uniqueldentity in A unique integer value which identifies one or many 


demand subscriptions or/and operation executions. 


Description 


The bciDoRequest performs the reading(s) initialized through bciGetAttributes, 
bciGetAttributes WithInit and / or executes the operations initialized by bciExecOperations and 
bciGetAttributesWithInit. This means that all the data areas pointed at by the values parameter 
of the bciGetAttributes calls will be updated. The results of each object access are available in 
the status arrays. Consequently, the current information pointed at by the arguments pointer is 
used as arguments to the executed operations. 
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5.11.2 Example 


Return Values 


bciSUCCESS 
bciAPI_EXE_FAILED 
bciAPI_LRESOURCE_LACK 
bciALLOCATION 
bciERRONEOUS_CAPS 
bciREFERENCE 
bciNO_MATCHING_CAP 
bciNO_PRIVILEGE 


/* 


* /opt/advant/UserAPI/examples/bciDoRequest 
* 


* Request attributes from two AI objects, 


objects, DI1 and DI2. 
avs 
#tinclude <stdio.h> /* 
#include <stdlib.h> /* 
#tinclude <bciUserAPI.h> /* 
#include <omf_AI.h> /* 
#include <omf_DI.h> /* 


#define NO_AI_OBJECTS 2 
#define NO_DI_OBJECTS 2 


#define NO_AI_ATTRIBS 3 


/* Three attributes from each AI object, 


/* Two attributes from each DI object, 


Successful completion 

System function has failed 

Could not allocate memory 

Could not allocate OMF resource 

One or more capabilities are erroneous 
Invalid unique identity 

All capabilities are erroneous or pending 


Privilege not allowed 


ea) 
*~ 
Q 


AI1l and AI2, and two DI 


printf */ 

exit */ 

UserAPI include file */ 
Object Type include file */ 
Object Type include file */ 


VALUE, UNIT */ 


STATUS, 


STATUS, DESCRIPTION */ 


#define NO_DI_A RIBS 2 

void main() 
{ 
int attIdx; 
int ob jIdx; 
int repIdx; 
int identity; 
BciStatus result; 
BciObjStatus** ai_objStatus; 
BciObjStatus** di_objStatus; 
void*** ai_values; 
void*** di_values; 


/* Array of object names */ 


const char* 


ai_objNames[] = {‘AI1”, 


“AI2"}; 
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const char* di_objNames[] = {“DI1”, “DI2"}; 

/* Array of attribute id’s, see omf_AI.h resp. omf_DI.h */ 

int ai_attributes_id[NO_AI_ATTRIBS] = {OMF_AIVALUEID, 
OMF_AISTATUSID, 
OMF_AIUNITID}; 

int di_attributes_id[NO_DI_ATTRIBS] = {OMF_DISTATUSID, 
OMF_DIDESCRIPTIONID},; 


/* Array of attribute sizes, see omf_AI.h resp. 


omf_DI.h */ 


TUS), 


[) }; 


size_t ai_valueSizes [NO_AI_ATTRIBS] = {sizeof (Omf_AIVALUE) , 
sizeof (Omf_AISTAT 
sizeof (Omf_AIUNIT 

size_t di_valueSizes[NO_DI_ATTRIBS] = {sizeof (Omf_! 


DISTATUS), 


sizeof (Omf_DID 


#ifdef __hpux 
_main(); 
#endif 


/* Create unique request identifier */ 
result bciCreateRequest (&identity, 0); 
if (result bciSUCCESS) 

{ 

printf (“bciCreateRequest () 

exit(1); 

} 


ERROR %d\n", 


result); 


/* Allocate 
ai_values 


memory for data */ 
bciAllocAttributes (NO_AI_OBJEC 
NO_AI_ATTRIBS, 
ai_valueSizes); 
bciAllocAttributes (NO_DI_OBJECTS, 
NO_DI_ATTRIBS, 
di_valueSizes); 
ai_objStatus bciAllocObjectStatus (NO_AI_OBJ 
di_objStatus bciAllocObjectStatus (NO_DI_OBJ: 
if (ai_objStatus == NULL || ai_values == NULL 
di_objStatus == NULL || di_values NULL) 


S, 


di_values 


By 


Cc 
EC 
| 


{ 

printf (“Out of memory\n”); 
exit(1); 

} 


/* Set up Request for values of object attributes... 
result bciGetAttributes (ai_objNames, 
NO_AI_OBJECTS, 
ai_attributes_id, 
NO_AI_ATTRIBS, 
ai_valueSizes, 
ai_values, 
ai_objStatus, 
identity); 
ESS) 


bciSUCCl 


if (result 


{ 


printf (“bciGetAttributes() AI ERROR %d\n”, 


result); 


ESCRIPTION) }; 


/* Run constructor for C++ as program coded in C */ 


a7 
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} 
result = bciGetAttributes (di_objNames, 
NO_DI_OBJECTS, 
di_attributes_id, 
NO_DI_ATTRIBS, 
di_valueSizes, 
di_values, 
di_objStatus, 
identity); 
if (result != bciSUCCESS) 
{ 
printf (“bciGetAttributes() DI ERROR %d\n”, result); 


} 


/* Repeat demands 3 times... */ 

for (repIdx = 0; repIdx < 3; repIdx++) 
{ 
/* Perform the request... */ 
result = bciDoRequest (identity) ; 


/* Show AI objects... */ 
printf (“OBJECT NAME\tOBJ STATUS\tSTATUS\tVALUE\tUNIT\n”) ; 
for (objIdx = 0; objIdx < NO_AI_OBJECTS; objIdx++) 
{ 
printf (“%s\t\t%d", 
ai_objNames [objIdx], ai_objStatus [objIdx]->codes) ; 
if (ai_objStatus [objIdx]->codes == bciOBJ_SUCCESS) 
{ 
printf (“\t\t%lu\t%5.2£\t%s"”, 
* ((Omf_AISTATUS*) ai_values [objIdx][1]), 
*((Omf_AIVALUE*) ai_values[objIdx][0]), 
* ((Omf_AIUNIT*) ai_values [objIdx] [2])); 


} 
printf (“\n"); 
} 
/* Show DI objects... */ 
printf (“OBJECT NAME\tOBJ STATUS\tSTATUS\tDESCRIPTION\n”) ; 
for (objIdx = 0; objIdx < NO_DI_OBJECTS; objIdx++) 
{ 
printf (“%s\t\t%d", 
di_objNames [objIdx], di_objStatus [objIdx]->codes) ; 
if (di_objStatus [objIdx]->codes == bciOBJ_SUCCESS) 
{ 
printf (“\t\t%lu\t%s”, 
* ((Omf_DISTATUS*) di_values [objIdx][0]), 
* ((Omf_DIDESCRIPTION*) di_values[objIdx][1])); 


} 
printf (“\n"); 
} 
printf(“\n"); 
} 


/* Remove requests connected with unique identifier */ 
/* (Actully dont needed in this case because the identifier is */ 
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/* deleted in the bciDeleteRequest call 3 lines below) */ 
result = bciCancelRequest (ai_objNames, NO_AI_OBJECTS, identity); 
result = bciCancelRequest (di_objNames, NO_DI_OBJECTS, identity); 


/* Delete unique request identifier */ 
result = bciDeleteRequest (&identity) ; 


/* Deallocate memory used */ 

bciFreeAttributes (NO_AI_ OBJECTS, NO_AI_ATTRIBS, ai_values); 
bciFreeAttributes (NO_DI_OBJECTS, NO_DI_ATTRIBS, di_values) ; 
bciFreeObjectStatus (NO_AI_OBJECTS, ai_objStatus) ; 
bciFreeObjectStatus (NO_DI_OBJECTS, di_objStatus) ; 

} 


5.12 bciDeleteRequest 


5.12.1 Description 


This service deletes all requests identified with the unique identity number. 


Synopsis 
#include <bciUserAPI.h> 


BciStatus bciDeleteRequest ( 


const int* uniqueIdentity); 
Parameters 
Par. Name: Direction: Description: 
uniqueldentity in A unique integer value which identifies one or many 


demand subscriptions or operation executions. 


Description 


The bciDeleteRequest function deletes all permanent subscriptions that were set up using 
bciGetAttributes, bciGetAttributesWithInit and bciExecOperations which are identified through 
the identifier. 


Return Values 


bciSUCCESS Successful completion 
bciREFERENCE Invalid unique identity 


5.12.2 Example 


See Section 5.11, bciDoRequest. 
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5.13 bciCancelRequest 


5.13.1 Description 


This service deletes one or several requests identified with the unique identity number and 
object name. 


Synopsis 
#include <bciUserAPI.h> 


BciStatus bciCancelRequest ( 


const char** objectNames, 
int objectCount, 
int uniqueIdentity); 

Parameters 

Par. Name: Direction: Description: 

objectNames in Array with names of the object instances from which to get 

attributes. 
objectCount in number of object names in the objectNames array 
uniqueldentity in A unique integer value which identifies one or many 


demand subscriptions or operation executions. 


Description 


The bciCancelRequest function deletes all permanent connections that were set up using 
bciGetAttributes, bciGetA ttributes WithInit and bciExecOperations which are identified through 
the identifier and object name. 


Return Values 


bciSUCCESS Successful completion 
bciREFERENCE Invalid unique identity 


5.13.2 Example 


See Section 5.11, bciDoRequest. 
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5.14 bciGetAttributes 


5.14.1 Description 


This service reads attribute values from object instances. 


Synopsis 


#include <bciUserAPI.h> 


BciStatus bciGetAttributes ( 


const char** objectNames, 

int objectCount, 

const int* attributes, 

int attributeCount, 

const size_t* valueSizes, 

void*** values, 

BciObjStatus** status, 

int uniqueIdentity); 
Parameters 
Par. Name: Direction: Description: 
objectNames in Atray of names of the object instances to get attribute 

values from 
objectCount in Number of object names in the objectNames array 
attributes in Array with attribute identifiers to get values from 
attributeCount in Number of attribute identifiers in the attributes array 
valueSizes in Sizes of the areas where the attribute values are stored 
values in/out Array of pointers to array of pointers to data areas where 
attribute values are stored 

status out Pointer to array of status, one status per object 
uniqueldentity in A unique integer value which identifies the request 
Description 


The attribute identifiers in the attributes array are obtained from an Object Type include file. 
The Object Type include file is also used to get the data types of the attribute values. 


The bciGetAttributes function verifies that the requested attributes are part of the Object Type 
that the object instances belong to and that the valueSizes are correct. 


The bciGetAttributes function can not verify that the correct data types are used for the 
attribute values, that is the callers responsibility. 
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When uniqueldentity = 0 the bciGetAttributes function reads a number of attribute values 
from a number of object instances of the same Object Type. 


If the parameter uniqueldentity is given a value > 0 the beiGetAttributes will provide a 
different functionality. It will initialize a demand reading of attribute values but it will not 
perform the reading. The status returned to the caller will only show if the connection to each of 
the objects has succeeded or not. See Section 5.10, bciCreateRequest. 


Return Values 


bciSUCCESS Successful completion 

bciAPI_EXE_ FAILED System function has failed 
bciAPI_RESOURCE_LACK Could not allocate memory 

bciAPL ERR ATTRIB Incorrect attribute specification 
bciAPI_ERR_OPER Incorrect operation specification 
bciAPIL ERR EVENT Incorrect event specification 
bciAPI_ERR_VALSIZE Incorrect attribute size specified 
bciAPI_ERR_OPSIZE Incorrect operation size specified 
bciAPI_ERR_EVSIZE Incorrect event size specified 
bciALLOCATION Could not allocate OMF resource 
beiILLEGAL_NAME Illegal characters in all given symbol names 
bciREFERENCE Invalid unique identity 

bciTYPE Illegal object type name 
bciNO_PRIVILEGE Privilege not allowed 
bciNO_TRANSLATION Illegal Attribute, Operation or Event 
bciNO_MATCHING_CAP All capabilities are erroneous or pending 
bciERRONEOUS_CAPS One or more capabilities are erroneous 


See Section A.3, Status Codes from Object Access Services for translation of the object status 
code. 
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5.14.2 Example 


/* 


* /opt/advant/UserAPI/examples/bciGetAttributesEx.c 


* 


* Request attributes from two AI objects, 


*/ 


#include <stdio.h> 
#include <bciUserAPI.h> /* 
#include <omf_AI.h> 


#define NO_OBJ 


/* printf */ 
UserAPI include 


ECTS 2 


AI1l and AI2. 


file */ 


/* Object Type include file */ 


/* Three attributes from each object, VALUE, STATUS and UNIT */ 
#define NO_ATTRIBS 3 
void main () 

{ 

int attIdx; 

int ob jIdx; 

BciStatus result; 

BciObjStatus** objStatus; 

void*** values; 

/* Array of object names */ 

const char* objNames[] = {“AI1”, “AI2"}; 


/* Array of 
int 


/* Array of 
size_t 


#ifdef __hpux 
_main(); /* 
#endif 


/* Allocate 


attribute id’s, 


attribute sizes, see omf_AI 
valueSizes [NO_ATTRIBS 


see omf_AI.h */ 
attributes_id[NO_ATTRIBS] = 


{OMF_AIVALUEID, 
OMF_ATISTATUSID, 
OMF_ATIUNITID}; 

2h ef 

] = {sizeof (Omf_AIVALUE), 

sizeof (Omf_AISTATUS), 
sizeof (Omf_AIUNIT) }; 


Run constructor for C++ as program coded in C */ 


memory for data */ 


NO_ATTRIBS, valueSizes); 


ECTS); 


values = bciAllocAttributes (NO_OBJECTS, 
objStatus = bciAllocObjectStatus (NO_OBJ 
if (objStatus == NULL || values == NULL) 

{ 

printf (“Out of memory\n”); 


} 


/* Request for values of object attributes... 
bciGetAttributes (objNames, 


result = 


NO_OBJECTS, 
attributes_id, 
NO_ATTRIBS, 
valueSizes, 
values, 

ob jStatus, 

0); 


if: 


3BSE 011 011R0101 


5-27 


Advalnform® User API User’s Guide 
Chapter 5 Object Access Services 


if (result 
{ 


printf (“bciGetAttributes () 


} 
else 


{ 


bciSUCCE 


printf (“OBJ 


ECT NAME 


SS) 


ERROR %d\n”, result); 


US\tVALUE\t\tUNIT\n”) ; 


\t\tOBJ STAT 


for (objIdx = 
{ 


0; 


printf (“%s\t%d\t”, 


if (objStatus[ob 


{ 
/* Print each 


objIdx < NO_OBJECTS; 


objIdx++) 


objNames[objIdx], ob jStatus [objIdx]->codes) ; 
jIdx]->codes == bciOBJ_SUCCESS) 


attribute valu Note the array index, */ 


/* it must correspond to the array of attribute id’s */ 
printf (“\tSlu\t\t%5.2f\t\t%ss”, 


* ( (Omf_AISTAT 
Omf_AIVALUI 
Omf_AIUNIT*) values [ob jIdx][2])); 


*( 


* ( 
} 
printf (“\n"); 
} 


US*) values [ob jIdx][1]), 
E*) values [objIdx] [0]), 


/* Deallocate memory used */ 


bciFreeAttributes (NO_OBJECTS, 
bciFreeObjectStatus (NO_OBJECTS, 


} 


5.15 bciGetAttributesWithlInit 


5.15.1 Description 


NO_ATTRIBS, values); 
ob jStatus) ; 


This function reads attribute values from object instances with an initialize operation. 


Synopsis 


#include <bciUserAPI.h> 


BceiStatus bciGetAttributesWithInit ( 


const char** 
int 

const int* 

int 

const size_t* 
void*** 
BciObjStatus** 
int 

size_t 

void** 


int 


objectNames, 
objectCount, 
attributes, 
attributeCount, 
valueSizes, 
values, 

status, 
operation, 
argSize, 
arguments, 
uniqueIdentity); 
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Parameters 

Par. Name: Direction: Description: 

objectNames in Atray of names of the object instances to get attribute 
values from 

objectCount in Number of object names in the objectNames array 

attributes in Array with attribute identifiers to get values from 

attributeCount in Number of attribute identifiers in the attributes array 

valueSizes in Sizes of the areas where the attribute values are stored 

values in/out Array of pointers to array with pointers to data areas where 
attribute values are stored. 

status out Pointer to array of status, one status per object. 

operation in Operation identifier 

argSize in Size of the argument data 

arguments in/out Array with pointers to areas where argument data is stored. 

uniqueldentity in A unique integer value which identifies the request 

Description 


The bciGetAttributesWithInit function does the same thing as the beiGetAttributes function 
but adds an initialization operation. The initialization operation provides the means to send 
information to the object instance on how to get the attribute values. As an example it could be 
used when the Object Type contains a large array and only a part of the array should be returned. 
The attribute identifiers in the attributes array and the operation identifier are obtained from an 
Object Type include file. The Object Type include file is also used to get the data types of the 
attribute values and operation argument. 


When uniqueldentity = 0 the bciGetAttributesWithInit function reads a number of attribute 
values from a number of object instances of the same Object Type. 


When uniqueldentity > 0 the bciGetAttributesWithInit function initializes a demand reading 
of attribute values with init (including the object name translations) but it will not perform the 
reading. 


The bciGetAttributesWithInit function verifies that the requested attributes and the operation 
are part of the Object Type that the object instances belong to and that the valueSizes and 
argSize are correct. The function can not verify that the correct data types are used for the 
attribute values and argument data, that is the callers responsibility. 
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Return Values 


bciSUCCESS 
bciAPI_EXE_FAILED 
bciAPIRESOURCE_LACK 
bciAPI_ERR_ATTRIB 
bciAPI_ERR_OPER 
bciAPI_ERR_EVENT 
bciAPI_ERR_VALSIZE 
bciAPI_LERR_OPSIZE 
bciAPI_ERR_EVSIZE 
bciALLOCATION 
beiILLEGAL_NAME 
bciREFERENCE 

bciTYPE 
bciNO_PRIVILEGE 
bciNO_TRANSLATION 
bciNO_MATCHING_CAP 
bciERRONEOUS_CAPS 


Successful completion 

System function has failed 

Could not allocate memory 

Incorrect attribute specification 
Incorrect operation specification 
Incorrect event specification 

Incorrect attribute size specified 
Incorrect operation size specified 
Incorrect event size specified 

Could not allocate OMF resource 

Illegal characters in all given symbol names 
Invalid unique identity 

Illegal object type name 

Privilege not allowed 

Illegal Attribute, Operation or Event 

All capabilities are erroneous or pending 


One or more capabilities are erroneous 


See Section A.3, Status Codes from Object Access Services for translation of the object status 


code. 


/* 


* /opt/advant/UserAPI/examples/bciGetAttributesWithInitEx.c 


* 


* Request attributes from two AI objects, AI1 and AI2. 


*/ 


#include <stdio.h> 


/* printt */ 


#include <bciUserAPI.h> /* UserAPI include file */ 


#include <omf_AI.h> 
#include <dccodes.hh> 


#define NO_OBJECTS 2 


/* Object Type include file */ 
/* Master specific operation codes */ 


/* Three attributes from each object, VALUE, STATUS and UNIT */ 


#define NO_ATTRIBS 3 
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void main () 


int attIdx; 

int ob jIdx; 

BciStatus result; 

BciObjStatus** objStatus; 

VoLld*** values; 

/* Array of object names */ 

const char* objNames[] = {“AI1”, “AI2"}; 


/* Array of attribute id’s, see omf_AI.h */ 


int attributes_id[NO_ATTRIBS] = {OMF_AIVALUEID, 
OMF_AISTATUSID, 
OMF_AIUNITID}; 


/* Array of attribute sizes, see omf_AI.h */ 
size_t valueSizes[NO_ATTRIBS] = {sizeof 


(Om£_AIVALUE), 


sizeof (Omf_AISTATUS), 
sizeof (Omf_AIUNIT) }; 


/* Operation parameters */ 


int operation = OMF_AIORDERID; 
size_t operSize = sizeof (Omf_AIORDER) ; 
Omf£_ATORDER** operArg; 


#ifdef __hpux 


_main(); /* Run constructor for C++ as program coded in C */ 


#endif 


/* Allocate memory for data */ 


values = bciAllocAttributes (NO_OBJECTS, NO_ATTRIBS, valueSizes) ; 
operArg = (Omf_AIORDER**)bciAllocOperations (NO_OBJECTS, operSize); 


objStatus = bceiAllocObjectStatus (NO_OBJECTS) ; 
if (objStatus == NULL || operArg == NULL || values 
{ 
printf (“Out of memory\n”); 
} 
/* Define operation for each object (Sets value to 
for (objIdx = 0; objIdx < NO_OBJECTS; objIdx++) 
{ 
operArg [objIdx]->opCode= dcVALUE_CHANGE_DCX; 
operArg[objIdx]->opProp= dcACT_VALUE_DCX; 
operArg [objIdx]->typeOfReq= dcPROG; 
operArg [objIdx]->eventLog= 0; 
operArg [objIdx]->dialogId= 0; 
operArg[objIdx]->aValue= 34.0; 
operArg[objIdx]->status= 0; 
operArg [objIdx]->textIndex= 0; 
} 


== NULL) 


34.0) */ 
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/* Request for values of object attributes... */ 

result = bciGetAttributesWithInit (objNames, 
NO_OBJECTS, 
attributes_id, 
NO_ATTRIBS, 
valueSizes, 
values, 
ob jStatus, 
operation, 
operSize, 
(void**) operArg, 
0); 


if (result != bciSUCCESS) 
{ 
printf (“bciGetAttributesWithInit() ERROR %d\n”, result); 
} 
else 
{ 
printf (“OBJECT NAME\t\tOBJ STATUS\tVALUE\t\tUNIT\n”) ; 
for (objIdx = 0; objIdx < NO_OBJECTS; objIdx++) 
{ 
printf (“%s\t%d\t”, objNames[objIdx], objStatus [objIdx]->codes) ; 
if (objStatus[objIdx]->codes == bciOBJ_SUCCESS) 
{ 
/* Print each attribute value. Note the array index, */ 
/* it must correspond to the array of attribute id’s */ 
printf (“\tSlu\t\t%5.2f\t\t%s”, 
* ((Omf_AISTATUS*) values [objIdx][1]), 
* ((Omf_AIVALUE* ) values [objIdx][0]), 
* ((Om£_AIUNIT*) values [objIdx][2])); 


} 
printf(“\n"); 
} 


/* Deallocate memory used */ 

bciFreeAttributes (NO_OBJECTS, NO_ATTRIBS, values); 
bciFreeOperations (NO_OBJECTS, (void**) operArg) ; 
bciFreeObjectStatus (NO_OBJECTS, objStatus) ; 

} 


5.16 bciGetAttributesCyclic 
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5.16.1 Description 


This function reads attribute values from object instances cyclically. The function creates a 
permanent subscription that exists until it is removed. 


Synopsis 


#include <bciUserAPI.h> 


BciStatus bciGetAttributesCyclic ( 


const char** objectNames, 
int objectCount, 
void** references, 
const int* attributes, 
int attributeCount, 
const size_t* valueSizes, 
void*** values, 
BciObjStatus** status, 
double cycleTime, 
void (*cyclicFunction) ( 
const char* objectName, 
void* reference, 
BciObjStatus status, 
const int* attributes, 
int attributeCount, 
void** values) ); 
Parameters 
Par. Name: Direction: Description: 
objectNames in Array of names of the object instances to get attribute 
values from 
objectCount in Number of object names in the objectNames array 
references in Atray of user defined references connected with objects in 
object array. Could be set to NULL. 
attributes in Array with attribute identifiers to get values from 
attributeCount in Number of attribute identifiers in the attributes array 
valueSizes in Sizes of the areas where the attribute values are stored 
values in/out Array of pointers with pointers to data areas where the 
attribute values are stored 
status out Array of status, one status per object 
cycleTime in Time in seconds between each get of attribute values 
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cyclicFunction in Pointer to function that is called when the data is received 
from an object instance 


objectName in Name of the object that has sent data 

reference in User defined reference 

status in Status of the object access 

attributes in Array with attribute identifiers 

attributeCount in number of attribute identifiers in the attributes array and 


number of values in the values array 


values in Array with pointers to attribute data 


Description 


The bciGetAttributesCyclic function gets attribute values cyclically. The 

bciGetA ttributesCyclic function sets up a permanent subscription with the specified 
cycleTime, so that the cyclicFunction will be called whenever a cycle ends. The actual call of the 
cyclicFunction is done from the beiGetData function. 


To remove the subscription the bciCancelGet function should be called!. The attribute 
identifiers in the attributes array are obtained from an Object Type include file. The Object Type 
include file is also used to get the data types of the attribute values. The 

bciGetA ttributesCyclic function verifies that the requested attributes are part of the Object 
Type that the object instances belong to and that the valueSizes are correct. The function can not 
verify that the correct data types are used for the attribute values, that is the callers 
responsibility. 


1. It is essential that the subscription is removed before the application terminates. 
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Return Values 


bciSUCCESS 
bciAPI_EXE_FAILED 
bciAPI_RESOURCE_LACK 
bciAPI_ERR_ATTRIB 
bciAPI_LERR_OPER 
bciAPIERR_EVENT 
bciAPI_ERR_VALSIZE 
bciAPI_ERR_OPSIZE 
bciAPI_ERR_EVSIZE 
bciALLOCATION 
beiILLEGAL_NAME 
bciREFERENCE 

bciTYPE 
bciNO_PRIVILEGE 
bciNO_TRANSLATION 
bciNO_MATCHING_CAP 
bciERRONEOUS_CAPS 


Advalnform® User API User’s Guide 
Section 5.16.2 Example 


Successful completion 

System function has failed 

Could not allocate memory 

Incorrect attribute specification 
Incorrect operation specification 
Incorrect event specification 

Incorrect attribute size specified 
Incorrect operation size specified 
Incorrect event size specified 

Could not allocate OMF resource 

Illegal characters in all given symbol names 
Invalid unique identity 

Illegal object type name 

Privilege not allowed 

Illegal Attribute, Operation or Event 

All capabilities are erroneous or pending 


One or more capabilities are erroneous 


See Appendix A, Status Codes for translation of the object status code. 


/* 


* /opt/advant/UserAPI/examples/bciGetAttributesCyclicEx.c 


* 


* Request attributes cyclically from two AI objects, AI1 and AI2. 


a) 


#include <stdio.h> 


/* printf */ 


#include <bciUserAPI.h> /* UserAPI include file */ 


#include <omf_AI.h> 


#define NO_OBJECTS 2 


/* Object Type include file */ 


/* Two attributes from each object, VALUE and STATUS */ 
#define NO_ATTRIBS 2 


void treatCyclicData(const char*objectName, 
void* reference, 
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BciObjStatus objStatus, 


const int* attributes, 
int attributeCount, 
void** values) 

{ 

int attIdx; 

BciStatus result; 


BciObjStatus* status; 


if (objStatus.codes == bciOBJ_SUCCESS) 
{ 
printf (“AI *%s’ has STATUS %lu and VALUE %5.2f\n", 
objectName, 
* ((Omf_AISTATUS*)values[1]), 
* ((Omf_AIVALUE*) values[0])); 


3 


} 
else 

{ 

result = bciGetCapStatus (objectName, &status); 

if (result != bciSUCCESS) 
{ 
printf (“bciGetCapStatus() ERROR %d\n”, result); 
return; 
} 

for (attIdx = 0; attIdx < attributeCount; attIdx+t+) 
{ 
printf(“AI %s Attribute %d access status code %d\n”, 

objectName, attributes[attIdx], status[attIdx].codes); 


void main() 


int attIdx; 

int ob jIdx; 

BciStatus result; 

BciObjStatus** objStatus; 

void*** values; 

/* Array of object names */ 

const char* objNames[] = {*AIC71_1”, “AIC71_2”}; 

/* Array of attribute id’s, see omf_AI.h */ 

int attributes_id[NO_ATTRIBS] = {OMF_AIVALUEID, 


OMF_AISTATUSID}; 
/* Array of attribute sizes, see omf_AI.h */ 
size_t valueSizes[NO_ATTRIBS] = {sizeof (Omf_AIVALUE), 
sizeof (Omf_AISTATUS) }; 


#ifdef __hpux 
_main(); /* Run constructor for C++ as program coded in C */ 
#endif 


/* Allocate memory for data */ 
values = bciAllocAttributes (NO_OBJECTS, NO_ATTRIBS, valueSizes); 
objStatus = bciAllocObjectStatus (NO_OBJECTS) ; 


5-36 3BSE 011 011R0101 


Advalnform® User API User’s Guide 
Section 5.16.2 Example 


if (objStatus == NULL || values == NULL) 
{ 
printf (“Out of memory\n”); 


} 


/* Subscribe cyclically for values of object attributes */ 
/* with a period of 9 secunds */ 
result = bciGetAttributesCyclic(objNames, 
NO_OBJECTS, 
NULL; 
attributes_id, 
NO_ATTRIBS, 
valueSizes, 
values, 
ob jStatus, 
9, /* Cycle time */ 
treatCyclicData) ; 


if (result != bciSUCCESS) 
{ 
printf (“bciGetAttributesCyclic() ERROR %d\n”, result); 
} 
else 
{ 
for (objIdx = 0; objIdx < NO_OBJECTS; objIdx++) 
{ 
if (objStatus[objIdx]->codes != bciOBJ_SUCCESS) 
{ 
printf(“%s object status = %d\n", 
objNames[objIdx], objStatus[objIdx]->codes) ; 


} 
/* Subscribe for data in 60 seconds... */ 
result = beiGetData(60); 
if (result != bciSUCCESS) 
{ 
printf (“bciGetData() ERROR %d\n”, result); 
} 


/* Cancel all subscriptions */ 
bciCancelGet (objNames, NO_OBJECTS) ; 


/* Deallocate memory used */ 

bciFreeAttributes (NO_OBJECTS, NO_ATTRIBS, values); 
bciFreeObjectStatus (NO_OBJECTS, objStatus); 

} 
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5.17 bciGetAttributesCyclicWithInit 


5.17.1 Description 


The function gets attribute values cyclically with init. The subscription is permanent and exists 
until it is removed. 


Synopsis 
#include <bciUserAPI.h> 


BciStatus bciGetAttributesCyclicWithInit ( 


const char** objectNames, 
int objectCount, 
void** references, 
const int* attributes, 
int attributeCount, 
const size _t* valueSizes, 
void*** values, 
BciObjStatus** status, 
double cycleTime, 
void (*cyclicFunction) ( 
const char* objectName, 
void* reference, 
BciObjStatus status, 
const int* attributes, 
int attributeCount, 
void** values), 
int operation, 
size_t argSize, 
void** arguments); 
Parameters 
Par. Name: Direction: Description: 
objectNames in Array of names of the object instances to get attribute 


values from 
objectCount in Number of object names in the objectNames array 


references in Atray of user defined references connected with objects in 
object array 


attributes in Array with attribute identifiers to get values from 
attributeCount in Number of attribute identifiers in the attributes array 
valueSizes in Sizes of the areas where the attribute values are stored 
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values 


cycleTime 


cyclicFunction 


objectName 
reference 
status 
attributes 


attributeCount 


values 
operation 
argSize 


arguments 


Description 


in/out 


in 


in 


in 
in 
in 
in 


in 


in 
in 
in 


in/out 


Array of pointers to array with pointers to data areas where 
the attribute values are stored 


Time in seconds between each get of attribute values 


Pointer to function that will be called when the data is 
received from an object instance 


Name of the object that has sent data 
User defined reference 

Status of the object access 

Array with attribute identifiers 


Number of attribute identifiers in the attributes array and 
number of values in the values array 


Array with pointers to attribute 
Operation identifier 
Size of the argument data 


Atray of pointers to the area where argument data is stored 


The bciGetA ttributesCyclicWithInit function is the same as the bciGetAttributesCyclic 

function, but it also includes an initialization operation. The initialization operation provides the 
means to send information to the object instance on how to get the attribute values. The attribute 
identifiers in the attributes array and the operation identifier are obtained from an Object Type 
include file. The Object Type include file is also used to get the data types of the attribute values 
and operation argument. 


The bciGetA ttributesCyclicWithInit function verifies that the requested attributes and the 
operation are part of the Object Type that the object instances belong to and that the valueSizes 
and argSize are correct. The function can not verify that the correct data types are used for the 
attribute values and argument data, that is the callers responsibility. 
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5.17.2 Example 
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Return Values 


bciSUCCESS 
bciAPI_EXE_FAILED 
bciAPI_RESOURCE_LACK 
bciAPI_LERR_ATTRIB 
bciAPI_LERR_OPER 
bciAPI_ERR_EVENT 
bciAPI_ERR_VALSIZE 
bciAPI_ERR_OPSIZE 
bciAPI_ERR_EVSIZE 
bciALLOCATION 
beiILLEGAL_NAME 
bciREFERENCE 

bciTYPE 
bciNO_PRIVILEGE 
bciNO_TRANSLATION 
bciNO_MATCHING_CAP 
bciERRONEOUS_CAPS 


Successful completion 

System function has failed 

Could not allocate memory 

Incorrect attribute specification 
Incorrect operation specification 
Incorrect event specification 

Incorrect attribute size specified 
Incorrect operation size specified 
Incorrect event size specified 

Could not allocate OMF resource 

Illegal characters in all given symbol names 
Invalid unique identity 

Illegal object type name 

Privilege not allowed 

Illegal Attribute, Operation or Event 

All capabilities are erroneous or pending 


One or more capabilities are erroneous 


See Appendix A, Status Codes for translation of the object status code. 


See Section 5.15, bciGetAttributes WithInit and Section 5.16, bciGetAttributesCyclic. 
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5.18 bciGetAttributesOnEvent 


5.18.1 Description 


This function reads attribute values from object instances when a specific event is detected in 
the objects. The function creates a permanent subscription that exists until removed. 


Synopsis 


#include <bciUserAPI.h> 


BciStatus bciGetAttributesOnEvent ( 


const char** 
int 
void** 
const int* 
int 
const size_t* 
void*** 
BciObjStatus** 
int 
size t 
void** 
void (* 
const char* 
void* 
BciObjStatus 
const int* 
int 
void** 
int 
void* 


Parameters 


Par. Name: 


objectNames in 


objectCount in 


references in 


attributes in 
attributeCount in 


valueSizes in 


Direction: 


objectNames, 

objectCount, 

references, 

attributes, 

attributeCount, 

valueSizes, 

values, 

status, 

event, 

event Size, 

eventData, 

eventFunction) ( 
objectName, 
reference, 
status, 
attributes, 
attributeCount, 
values, 
event, 
eventData) ); 


Description: 


Array of names of the object instances to get attribute 
values from 


Number of object names in the objectNames array 


Array of user defined references connected with objects in 
object array 


Atray with attribute identifiers to get values from 
Number of attribute identifiers in the attributes array 


Sizes of the areas where the attribute values are stored 
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values in/out Array of pointers to array with pointers to data areas where 
attribute values are stored 


status out Pointer to array of status, one status per object 

event in Event identifier 

eventSize in Size of the data area where the event data is stored 
eventData in Pointer to the array data areas, one per object, where the 


event data is stored 


eventFunction in Pointer to function that is called when the data is received 
from one object instance 


objectName in Name of the object that has sent data 

reference in User defined reference 

Status in Status of the object access 

attributes in Array with attribute identifiers 

attributeCount in Number of attribute identifiers in the attributes array an 


number of values in the values array 


values in Array with pointers to data areas where the attribute data is 
received 
event in Event identifier 
eventData in Pointer to a data area where the event data is received 
Description 


The beiGetAttributesOnEvent function gets attribute values and eventData on event. On event 
means that when the object instance detects the event, data is sent to the caller and the 
eventFunction is called. 


The bciGetAttributesOnEvent function sets up a permanent subscription on the event, so that 
the eventFunction is called whenever the event is detected. The call of the eventFunction is done 
from the bciGetData function. To remove the subscription the beiCancelGet function should 
be called. It is essential that the subscription is removed before the application terminates. 

The attribute identifiers in the attributes array and the event identifier are obtained from an 
Object Type include file. The Object Type include file is also used to get the data types of the 
attribute values and eventData. 


The beiGetAttributesOnEvent function verifies that the requested attributes and event are part 
of the Object Type that the object instance belong to and that the valueSizes and eventSize are 
correct. The function can not verify that the correct data types are used for the attribute values 
and eventData, that is the callers responsibility. The eventFunction gets its arguments from the 
arguments to the bciGetAttributesOnEvent function. This means that these arguments can not 
be allocated on the stack, they must be static variables or allocated from the heap. 
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Return Values 


bciSUCCESS Successful completion 

bciAPI_EXE_ FAILED System function has failed 
bciAPI_RESOURCE_LACK Could not allocate memory 

bciAPL ERR ATTRIB Incorrect attribute specification 
bciAPI_ERR_OPER Incorrect operation specification 
bciAPL ERR EVENT Incorrect event specification 
bciAPI_ERR_VALSIZE Incorrect attribute size specified 
bciAPI_ERR_OPSIZE Incorrect operation size specified 
bciAPI_ERR_EVSIZE Incorrect event size specified 
bciALLOCATION Could not allocate OMF resource 
beiILLEGAL_NAME Illegal characters in all given symbol names 
bciREFERENCE Invalid unique identity 

bciTYPE Illegal object type name 
bciNO_PRIVILEGE Privilege not allowed 
bciNO_TRANSLATION Illegal Attribute, Operation or Event 
bciNO_MATCHING_CAP All capabilities are erroneous or pending 
bciERRONEOUS_CAPS One or more capabilities are erroneous 


See Appendix A, Status Codes for translation of the object status code. 


/* 
* /opt/advant/UserAPI/examples/bciGetAttributesOnEventEx.c 


* 


* Request attributes on events from two AI objects, AI1 and AI2. 
a) 


#include <stdio.h> /* printf */ 
#include <bciUserAPI.h> /* UserAPI include file */ 
#include <omf_AI.h> /* Object Type include file */ 


#define NO_OBJECTS 2 
/* Two attributes from each object, VALUE and STATUS */ 
#define NO_ATTRIBS 2 
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void treatEventData(const char* objectName, 

void* reference, 
BciObjStatus objStatus, 
const int* attributes, 
int attributeCount, 
void** values, 
int event, 
void* eventData) 

{ 

if (objStatus.codes == bciOBJ_SUCCESS) 

printf(‘“AI *%s’ has STATUS %lu and VALUE %5.2f\n", 
objectName, 


* ((Omf_AISTATUS*)values[1]), 
* ((Omf_AIVALUE*) values[0])); 


else 
printf(“AI %s Object status code %d\n"”, 
objectName, objStatus.codes) ; 


void main() 


int attIdx; 

int ob jIdx; 

BciStatus result; 

BciObjStatus** objStatus; 

void*** values; 

/* Array of object names */ 

const char* objNames[] = {“AI1”, “AI2"}; 

/* Array of attribute id’s, see omf_AI.h */ 

int attributes_id[NO_ATTRIBS] = {OMF_AIVALUEID, 


OMF_AISTATUSID}; 
/* Array of attribute sizes, see omf_AI.h */ 


size_t valueSizes[NO_ATTRIBS] = {sizeof (Omf_AIVALUE), 
sizeof (Omf_AISTATUS) }; 

int event = OMF_AIEVENTID; 

size_t eventSize = 0; 

void** eventData; 


#ifdef __hpux 
_main(); /* Run constructor for C++ as program coded in C */ 
#endif 


/* Allocate memory for data */ 
values = bciAllocAttributes (NO_OBJECTS, 
NO_ATTRIBS, 
valueSizes); 
eventData = bciAllocEvents (NO_OBJECTS, eventSize); 
objStatus = beciAllocObjectStatus (NO_OBJECTS) ; 
if (objStatus == NULL || values == NULL) 
{ 
printf (“Out of memory\n”); 


} 
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/* Subscribe on event for values of object attributes */ 

result = bciGetAttributesOnEvent (objNames, 
NO_OBJECTS, 
NULL, 
attributes_id, 
NO_ATTRIBS, 
valueSizes, 
values, 
objStatus, 
event, 
eventSize, 
eventData, 
treatEventData); 


if (result != bciSUCCESS) 
{ 
printf (“bciGetAttributesOnEvent () ERROR %d\n”, result); 
} 
else 
{ 
for (objIdx = 0; objIdx < NO_OBJECTS; objIdx++) 
{ 
if (objStatus[objIdx]->codes != bciOBJ_SUCCESS) 
{ 
printf(“%s object status = %d\n", 
objNames[objIdx], ob jStatus [objIdx]-—>codes) ; 


} 
/* Subscribe for data in 60 seconds... */ 
result = beiGetData(60); 
if (result != bciSUCCESS) 
{ 
printf (“bciGetData() ERROR %d\n”, result); 
} 


/* Cancel all subscriptions */ 
bciCancelAll () ; 


/* Deallocate memory used */ 

bciFreeAttributes (NO_OBJECTS, NO_ATTRIBS, values); 
bciFreeEvents (NO_OBJECTS, eventData) ; 
bciFreeObjectStatus (NO_OBJECTS, objStatus); 

} 
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5.19 bciGetAttributesOnEventWithlInit 


5.19.1 Description 


This function gets attribute values and event data on event with an initialize operation. The 
function creates a permanent subscription that will exist until it is removed. 


Synopsis 


#include <bciUserAPI.h> 


BceiStatus bciGetAttributesOnEventWithIinit ( 


const char** 
int 
void** 
const int* 
int 
const size_t* 
void*** 
BciObjStatus** 
int 
size_t 
void** 
void 
const char* 
void* 
BciObjStatus 
const int* 
int 
void** 
int 
void* 
int 
size_t 
void** 


Parameters 


Par. Name: 


objectNames in 


objectCount in 


references in 


attributes in 


objectNames, 
objectCount, 
references, 
attributes, 
attributeCount, 
valueSizes, 
values, 
status, 
event, 
event Size, 
eventData, 
(*eventFunction) ( 
objectName, 
reference, 
status, 
attributes, 
attributeCount, 
values, 
event, 
eventData), 
operation, 
argSize, 
arguments); 


Direction: Description: 


Array of names of the object instances to get attribute 
values from 


Number of object names in the objectNames array 


Array of user defined references connected with objects in 
object array 


Array with attribute identifiers to get values from 
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attributeCount in Number of attribute identifiers in the attributes array 
valueSizes in Sizes of the areas where the attribute values are stored 
values in/out Array of pointers to array with pointers to data areas where 


the attribute values are stored 


status in Pointer to array of status, one status per object 

event in Event identifier 

eventSize in Size of the data area where the event data is stored 
eventData in Pointer to array of data areas, one per object, where the 


event data is stored 


eventFunction in Pointer to function that is called when the data is received 
from the object instance 


objectName in Name of the object that has sent data 

reference in User defined reference 

status in Status of the object access 

attributes in Atray with attribute identifiers 

attributeCount in Number of attribute identifiers in the attributes array and 


number of values in the values array 


values in Array with pointers to data areas where the attribute data is 
received 

event in Event identifier 

eventData in Pointer to a data area where the event data is received 
operation in Operation identifier 
argSize in Size of the argument data 
arguments in/out Array of pointers to the area where argument data is stored 
Description 


The bciGetA ttributesOnEventWithInit function is the same as the 

bciGetA ttributesOnEvent function, but it also includes an initialization operation. The 
initialization operation provides the means to send information to the object instance on how to 
get the attribute values. 


The attribute identifiers in the attributes array and the operation identifier are obtained from an 
Object Type include file. The Object Type include file is also used to get the data types of the 
attribute values and operation argument. The bciGetAttributesOnEventWithInit function 
verifies that the requested attributes and the operation are part of the Object Type that the object 
instances belong to and that the valueSizes and argSize are correct. The function can not verify 
that the correct data types are used for the attribute values and argument data, that is the callers 
responsibility. 
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Return Values 


bciSUCCESS 
bciAPI_EXE_FAILED 
bciAPI_RESOURCE_LACK 
bciAPI_LERR_ATTRIB 
bciAPI_LERR_OPER 
bciAPI_ERR_EVENT 
bciAPI_ERR_VALSIZE 
bciAPI_ERR_OPSIZE 
bciAPI_ERR_EVSIZE 
bciALLOCATION 
beiILLEGAL_NAME 
bciREFERENCE 

bciTYPE 
bciNO_PRIVILEGE 
bciNO_TRANSLATION 
bciNO_MATCHING_CAP 
bciERRONEOUS_CAPS 


Successful completion 

System function has failed 

Could not allocate memory 

Incorrect attribute specification 
Incorrect operation specification 
Incorrect event specification 

Incorrect attribute size specified 
Incorrect operation size specified 
Incorrect event size specified 

Could not allocate OMF resource 

Illegal characters in all given symbol names 
Invalid unique identity 

Illegal object type name 

Privilege not allowed 

Illegal Attribute, Operation or Event 

All capabilities are erroneous or pending 


One or more capabilities are erroneous 


See Appendix A, Status Codes for translation of the object status code. 


5.19.2 Example 


See Section 5.15, bciGetAttributes WithInit. 
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5.20 bciGetData 


5.20.1 Description 


The function gets the actual data that has been subscribed. 


Synopsis 
#include <bciUserAPI.h> 


BciStatus bciGetData ( 


float time) ; 
Parameters 
Par. Name: Direction: Description: 
time in Time to receive data (unit seconds) 
Description 


The bciGetData function gets data and calls the receiving function for all previously requested 
permanent subscriptions. Permanent subscriptions are set up with the 
bciGetAttributesOnEvent and the bciGetAttributesCyclic functions. 


The bciExitFromGetData function is useful when you issue bciGetData but receive a set of 
data. By calling beiExitFromGetData you return back to your program and can do whatever 
you like with the received data. Any data received in the meantime will be queued up. When 
you call bciGetData again, they will immediately be available. The queues for each attribute has 
20 positions, the same applies whether it is a cyclic or an event subscription. (This queue size 
can be changed with bciSetQueueSize.) If you do not return to bciGetData in time, and the 
queues are filled up, the oldest data will be lost. Overflow will, as all other data loss, be 
indicated by the objectStatus.flags set to beiOBJ_DATA_LOST. When you call bciGetData 
again the first received event will hold the oldest data (still in the queue) and loss of data will be 
indicated through the objectStatus.flags. After this the events will arrive in the order data was 
queued. 


The bciExitFromGetData can also be used by multi-threaded applications to exit bciGetData 
in any state. 


The time argument specifies for how long you stay in the bciGetData function and receive data. 
A negative time means that you never returns from the bciGetData function. If you want to exit 
from beiGetData when you have received the first set of data you call the function 
bciExitFromGetData 
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5.20.2 Example 


Return value 


bciSUCCESS Successful completion 
bciABORT Function aborted 
bciAPI_EXE FAILED System function has failed 
bciAPIRESOURCE_LACK Could not allocate memory 
bciNO_ASSOCIATION No subscriptions active 
bciAPI_ERR_TIMEOUT Time Out out of range 


See Section 5.16, bciGetAttributesCyclic. 


5.21 bciExitFromGetData 


5.21.1 Description 


5-50 


The function exits from the bciGetData wait state. 


Synopsis 
#include <bciUserAPI.h> 


BciStatus bciExitFromGetData (void) ; 


Parameters 


Description 


The bciExitFromGetData function is useful when you issue bciGetData and receive a set of 
data. By calling beiExitFromGetData you return back to your program and can do whatever 
you like with the received data. Any data received in the meantime will be queued up. When 
you call beiGetData again, they will immediately be available. See bciGetData for a description 
on how the queuing works. The function can also be used in multi-threaded applications to exit 


bciGetData event though no data has arrived or time-out has passed. 
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Return value 


bciSUCCESS Successful completion 
bciFAILURE Request failed 


5.21.2 Example 


/* User defined function to handle cyclic data */ 


void treatCyclicData(const char* objectName, 

void* reference, 
BciObjStatus objStatus, 
const int* attributes, 
int attributeCount, 
void** values) 

{ 

if (objStatus.codes == bciOBJ_SUCCESS) 


printf(‘“AI ‘%s’ has STATUS %lu and VALUE %5.2f\n"”, 
objectName, 
*((Omf_AISTATUS*)values[1]), 
* ((Omf_AIVALUE*) values[0])); 


else 
{ 
printf(“AI %s Object status code %d\n”, 
objectName, ob jStatus.codes) ; 
bciExitFromGetData () ; 
} 


/* Subscribe for data forever... */ 
result = bciGetData(-1); 


5.22 bciCancelGet 


5.22.1 Description 


The function cancels all subscriptions towards one or several object instances. 


Synopsis 
#include <bciUserAPI.h> 


BciStatus bciCancelGet ( 
const char** objectNames, 
int objectCount) ; 
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Parameters 
Par. Name: Direction: Description: 
objectNames in Array of name of the object instances to cancel 
subscription from 
objectCount in Number of object names in the objectName array to be 
cancelled, can be all objects in the array or parts of the 
array. 
Description 


The beiCancelGet function removes all previously requested permanent subscriptions from one 
or several object instances. Permanent subscription are set up with the 
bciGetAttributesOnEvent, bciGetAttributesCyclic, bciGetAttributesOnEventWithInit and 
the bciGetA ttributesCyclicWithInit functions. For MOD see example 
/UserAPI/examples/IMSEx7CncGet.c. 


Return Values 
bciSUCCESS Successful completion 


5.22.2 Example 


See for example Section 5.16, bciGetAttributesCyclic. 
5.23 bciCancelAll 


5.23.1 Description 


The function removes all subscriptions towards all object instances that the program/task has 


initiated. 


Synopsis 
#include <bciUserAPI.h> 


BciStatus bciCancelAl1l1 (void) ; 


Parameters 


None 
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Description 


The bciCancelAll function removes all previously requested permanent subscriptions. 
Permanent subscriptions are set up with the bciGetAttributesOnEvent, 
bciGetAttributesCyclic, bciGetAttributesOnEventWithInit and the 
bciGetAttributesCyclicWithInit functions. 


Return Value 


bciSUCCESS Successful completion 


See for example Section 5.15, bciGetAttributes With Init. 


5.24 bciExecOperations 


5.24.1 Description 


3BSE 011 011R0101 


The purpose of this function is to execute operations in object instances. Operations are the only 
way to update values in object instances. Which operations you can use per object type, and the 
Attributes they change, can be found in the AdvaInform Object Types Reference manual. See 
the Commands part for each object type. 


Synopsis 
#include <bciUserAPI.h> 


BciStatus bciExecOperations ( 


const char** objectNames, 
int objectCount, 
int operation, 
size_t argSize, 
void** arguments, 
BciObjStatus** status, 
int uniqueIdentity); 
Parameters 
Par. Name: Direction: Description: 
objectNames in Array with names of the object instances to execute the 


operation on 
objectCount in Number of object names in the objectNames array 


operation in Operation identifier 
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argSize in Size of the argument data 

arguments in/out Array of argument data, one per each object 

status out Pointer to array of status for object access, one per each 
object 

uniqueldentity in A unique integer value which identifies the request 

Description 


When uniqueldentity = 0 the bciExecOperations executes one operation on several object 
instances, where each operation can have different argument data. 


When uniqueldentity > 0 the bciGetAttributes function initializes the execution of a number of 
operations but it will not perform the reading. 


The Object Type include file is used to get the operation identifier. The Object Type include file 
is also used to get the data type for the argument data. The bciExecOperations function verifies 
that the operation identifier is part of the Object Type that the object instances belong to and that 
the argument size is correct. The function can not verify that the correct data types are used for 
the argument data, that is the callers responsibility. 


Return Value 


bciSUCCESS 
bciAPI_EXE_FAILED 
bciAPI_LRESOURCE_LACK 
bciAPI_LERR_ATTRIB 
bciAPI_LERR_OPER 
bciAPI_LERR_EVENT 
bciAPI_LERR_VALSIZE 
bciAPI_ERR_OPSIZE 
bciAPI_ERR_EVSIZE 
bciALLOCATION 
bceiILLEGAL_NAME 
bciREFERENCE 
bciTYPE 
bciNO_PRIVILEGE 
bciNO_TRANSLATION 


Successful completion 

System function has failed 

Could not allocate memory 
Incorrect attribute specification 
Incorrect operation specification 
Incorrect event specification 
Incorrect attribute size specified 
Incorrect operation size specified 
Incorrect event size specified 
Could not allocate OMF resource 
Illegal characters in all given symbol names 
Invalid unique identity 

Illegal object type name 
Privilege not allowed 


Illegal Attribute, Operation or Event 
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bciNO_MATCHING_CAP All capabilities are erroneous or pending 
bciERRONEOUS_CAPS One or more capabilities are erroneous 


See Appendix A, Status Codes for translation of the object status code. 


5.24.2 Example 
/* 


* /opt/advant/UserAPI/examples/bciExecOperationsEx.c 

* 

* Perform operation on two CCF_CONTIN_LOOP objects, LOOP1_DATA and 
LOOP2_DATA. 


*/ 
#include <stdio.h> /* printf */ 
#include <bciUserAPI.h> /* UserAPI include file */ 


#include <omf_CCF_CONTIN_LOOP.h> /* Object Type include file */ 
#define NO_OBJECTS 2 


void main () 


{ 


int ob jIdx; 
BciStatus result; 
BciObjStatus** objStatus; 
/* Array of object names */ 
const char* objNames[] = {“LOOP1_DATA”, “LOOP2_DATA”}; 
/* Operation parameters */ 
int operation = OMF_CCF_CONTIN_LOOPPUT_LP_STATEID; 
size_t operSize = 
sizeof (Omf_CCF_CONTIN_LOOPPUT_LP_STATE) ; 


Omf£_CCF_CONTIN_LOOPPUT_LP_STATE**operArg; 


#ifdef __hpux 
_main(); /* Run constructor for C++ as program coded in C */ 
#endif 


/* Allocate memory for data */ 

operArg = (Omf_CCF_CONTIN_LOOPPUT_LP_STATE**) 
bciAllocOperations (NO_OBJECTS, operSize); 

objStatus = beciAllocObjectStatus (NO_OBJECTS) ; 

if (objStatus == NULL || operArg == NULL) 


printf (“Out of memory\n”); 


/* Execute operations on objects... */ 

result = bciExecOperations (objNames, 
NO_OBJECTS, 
operation, 
operSize, 
(void**) operArg, 
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ob jStatus, 
0); 
if (result != bciSUCCESS) 
{ 


printf (“bciExecOperations() ERROR %d\n”, 


} 
else 
{ 
for (objIdx = 0; objIdx < NO_OBJECTS; 
{ 


if (objStatus[objIdx]->codes != bciOBJ_SUCC 


{ 


printf(“%s object status = %d\n"”, 


result); 


ESS) 


objNames[objIdx], ob jStatus[objIdx]->codes) ; 


/* Deallocate memory used */ 


bciFreeOperations (NO_OBJECTS, (void**) operArg) ; 
bciFreeObjectStatus (NO_OBJECTS, objStatus); 


} 


5.25 bciExecOperationsCyclic 


5.25.1 Description 


The purpose of this function is to execute operations cyclically in object instances. Operations 
are the only way to update values in object instances. Which operations you can use per object 
type, and the Attributes they change, can be found in the AdvaInform Object Types Reference 


manual. See the Commands part for each object type. 


Synopsis 
#include <bciUserAPI.h> 


BciStatus bciExecOperationsCyclic ( 


const char** objectNames, 
int objectCount, 
const void** references, 
int operation, 
size_t argSize, 
void** arguments, 
BciObjStatus** status, 
double cycleTime, 
void (*cyclicFunction) ( 
const char* objectName, 
const void* reference, 
BciObjStatus status, 
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int 
void* 


Parameters 


Par. Name: 


objectNames 


objectCount 


references 


operation 
argSize 
arguments 


Status 


cycleTime 


cyclicFunction 


objectName 
reference 
status 
operation 


argument 


Description 


Direction: 


in 


in 


in 


in 
in 
in/out 


out 


in 


in 


in 
in 
in 
in 


in 


Advalnform® User API User’s Guide 
Section 5.25.1 Description 


operation, 
argument) ); 


Description: 


Array with names of the object instances to execute the 
operation on 


Number of object names in the objectNames array 


Array of user defined references connected with objects in 
object array 


Operation identifier 
Size of the argument data 
Array of argument data, one per each object 


Pointer to array of status for object access, one per each 
object 


Time in seconds between each operation 


Pointer to function that is called when the operation is 
executed on an object instance 


Name of the object 

User defined reference 
Status of the object access 
Operation identifier 


Argument data 


The bciExecOperationsCyclic function sets up a permanent execute operation subscription 
with the specified cycleTime, so the cyclicFunction will be called whenever a cycle ends. The 
actual call of the cyclicFunction is done from the beiGetData function. 


The Object Type include file is used to get the operation identifier. The Object Type include file 
is also used to get the data type for the argument data. The bciExecOperationsCyclic function 
verifies that the operation identifier is part of the Object Type that the object instance belongs to 
and that the argument size is correct. The function can not verify that the correct data types are 
used for the argument data, that is the callers responsibility. 
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Return Value 


bciSUCCESS 
bciAPI_EXE_FAILED 
bciAPI_RESOURCE_LACK 
bciAPI_LERR_ATTRIB 
bciAPI_LERR_OPER 
bciAPI_ERR_EVENT 
bciAPI_LERR_VALSIZE 
bciAPI_ERR_OPSIZE 
bciAPI_ERR_EVSIZE 
bciALLOCATION 
beiILLEGAL_NAME 
bciREFERENCE 

bciTYPE 
bciNO_PRIVILEGE 
bciNO_TRANSLATION 
bciNO_MATCHING_CAP 
bciERRONEOUS_CAPS 


Successful completion 

System function has failed 

Could not allocate memory 

Incorrect attribute specification 
Incorrect operation specification 
Incorrect event specification 

Incorrect attribute size specified 
Incorrect operation size specified 
Incorrect event size specified 

Could not allocate OMF resource 

Illegal characters in all given symbol names 
Invalid unique identity 

Illegal object type name 

Privilege not allowed 

Illegal Attribute, Operation or Event 

All capabilities are erroneous or pending 


One or more capabilities are erroneous 


See Appendix A, Status Codes for translation of the object status code. 
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5.25.2 Example 


/opt/advant /UserAPI/examples/bciExecOperationsCyclicEx.c 


* Perform operation cyclically on two CCF_CONTIN_LOOP objects, 
LOOP1_DATA and 
LOOP2_DATA. 


* 
#include <stdio.h> /* printf */ 
#include <bciUserAPI.h> /* UserAPI include file */ 


#include <omf_CCF_CONTIN_LOOP.h> /* Object Type include file */ 


#define NO_OBJECTS 2 


void treatExecuteStatus(const char* objectName, 


void* reference, 
BciObjStatus objStatus, 
int operation, 
void* argument) 
{ 
if (objStatus.codes == bciOBJ_SUCCESS) 
printf (“Executed operation on *%s’\n", objectName) ; 


else 
printf(“%s Object status code %d\n”, 
objectName, objStatus.codes) ; 


void main () 


{ 


int ob jIdx; 

BciStatus result; 

BciObjStatus** objStatus; 

/* Array of object names */ 

const char* objNames[] = {“LOOP1_DATA”, “LOOP2_DATA”}; 

/* Operation parameters */ 

int operation = OMF_CCF_CONTIN_LOOPPUT_LP_STATEID; 
size_t operSize = sizeof (Omf_CCF_CONTIN_LOOPPUT_LP_STATE) ; 


Omf_CCF_CONTIN_LOOPPUT_LP_STATE**operArg; 


#ifdef __hpux 
_main(); /* Run constructor for C++ as program coded in C */ 
#endif 


/* Allocate memory for data */ 
operArg = (Omf_CCF_CONTIN_LOOPPUT_LP_STATE**) 
bciAllocOperations (NO_OBJECTS, operSize); 
objStatus = beciAllocObjectStatus (NO_OBJECTS) ; 
if (objStatus == NULL || operArg == NULL) 
{ 
printf (“Out of memory\n”); 


} 
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/* Execute operations cyclically with a period of 30 seconds... */ 


result = bciExecOperationsCyclic(objNames, 
NO_OBJECTS, 
NULL, 
operation, 
operSize, 
(void**) operArg, 
ob jStatus, 
30, /* Cycle time */ 
treatExecuteStatus) ; 


if (result != bciSUCCESS) 
{ 
printf (“bciExecOperationsCyclic() ERROR %d\n”, 
} 
else 
{ 
for (objIdx = 0; objIdx < NO_OBJECTS; objIdx++) 
{ 


if (objStatus[objIdx]->codes != bciOBJ_SUCCE 


{ 
printf(“%s object status = %d\n"”, 


result); 


objNames[objIdx], ob jStatus [ob jIdx] —->codes) ; 


} 


/* Wait for execute operation status in 60 seconds... */ 


result = beiGetData(60); 

if (result != bciSUCCESS) 
{ 
printf (“bciGetData() ERROR %d\n”, result); 
} 


/* Cancel all subscriptions */ 
bceiCancelAll () ; 


/* Deallocate memory used */ 

bciFreeOperations (NO_OBJECTS, (void**) operArg) ; 
bciFreeObjectStatus (NO_OBJECTS, objStatus); 

} 
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5.26 bciAllocAttributes 


5.26.1 Description 


5.26.2 Example 
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The purpose of this function is to easy allocate memory for the attribute value argument in 
UserAPI functions. 


Synopsis 
#include <bciUserAPI.h> 


void*** bciAllocAttributes ( 


int objectCount, 
int attributeCount, 
const size_t* valueSizes); 
Parameters 
Par. Name: Direction: Description: 
objectCount in Number of objects 
attributeCount in Number of attributes in the valueSizes array 
valueSizes in Array of attribute value sizes 
Description 


The bciAllocAttributes function allocates memory for the attribute data matrix and returns a 
pointer to that area. This pointer can be used for the values argument in for example the 
bciGetAttributes function. 


Return Value 


The allocated data or NULL if out of resources. 


See for example Section 5.14, bciGetAttributes. 
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5.27 bciAllocOperations 


5.27.1 Description 


The purpose of this function is to easy allocate memory for the operation argument in UserAPI 


functions. 


Synopsis 
#include <bciUserAPI.h> 


void** bciAllocOperations ( 


int objectCount, 
size_t argSize) ; 
Parameters 
Par. Name: Direction: Description: 
objectCount in Number of objects 
argSize in Size of operation 
Description 


The bciAllocOperations function allocates memory for the operation data array and returns a 
pointer to that area. This pointer can be used for the arguments argument in for example the 


bciExecOperations function. 


Return Value 


The allocated data or NULL if out of resources. 


5.27.2 Example 


See for example Section 5.24, bciExecOperations. 
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5.28 bciAllocEvents 


5.28.1 Description 


The purpose of this function is to easy allocate memory for the event data argument in UserAPI 
functions. 


Synopsis 
#include <bciUserAPI.h> 


void** bciAllocEvents ( 


int objectCount, 
size_t eventSize); 
Parameters 
Par. Name: Direction: Description: 
objectCount in Number of objects 
eventSize in Size of event data 
Description 


The beiAllocEvents function allocates memory for the event data array and returns a pointer to 
that area. This pointer can be used for the eventData argument in for example the 
bciGetAttributesOnEvent function. 


Return Value 


The allocated data or NULL if out of resources. 


5.28.2 Example 


See for example Section 5.18, bciGetAttributesOnEvent. 
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5.29 bciAllocObjectStatus 


5.29.1 Description 


5.29.2 Example 


The purpose of this function is to easy allocate memory for the object status argument in 
UserAPI functions. 


Synopsis 
#include <bciUserAPI.h> 


BciObjStatus** bciAllocObjectStatus ( 


int objectCount) ; 
Parameters 
Par. Name: Direction: Description: 
objectCount in Number of objects 
Description 


The bciAllocObjectStatus function allocates memory for the object status array and returns a 
pointer to that area. This pointer can be used for the st atus argument in for example the 
bciGetAttributes function. 


Return Value 


The allocated data or NULL if out of resources. 


See for example Section 5.14, bciGetAttributes. 


5.30 bciAllocObjectTypeNames 


5.30.1 Description 
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The purpose of this function is to easy allocate memory for the object type names argument in 
UserAPI functions. 


Synopsis 
#include <bciUserAPI.h> 


char** bciAllocObjectTypeNames ( 
int objectCount) ; 
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5.30.2 Example 
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Parameters 

Par. Name: Direction: Description: 
objectCount in Number of objects 
Description 


The bciAllocObjectTypeNames function allocates memory for the object type name array and 
returns a pointer to that area. This pointer can be used for the ob ject TypeNames argument 
in for example the bciResolveObjects function. 


Return Value 


The allocated data or NULL if out of resources. 


See for example Section 5.7, bciDataTypeElements. 


5.31 bciAllocObjectiDs 


5.31.1 Description 
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The purpose of this function is to easy allocate memory for the object ID argument in UserAPI 
functions. 


Synopsis 
#include <bciUserAPI.h> 


BciOID** bciAllocObjectIDs ( 


int objectCount) ; 
Parameters 
Par. Name: Direction: Description: 
objectCount in Number of objects 
Description 


The beiAllocObjectIDs function allocates memory for the object ID array and returns a pointer 
to that area. This pointer can be used for the oid argument in for example the 
bciGetObjectInformation function. 


Return Value 


The allocated data or NULL if out of resources. 
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5.31.2 Example 


See for example Section 5.8, bciGetObjectInformation. 
5.32 bciFreeAttributes 


5.32.1 Description 


The purpose of this function is to deallocate attribute data matrix. 


Synopsis 
#include <bciUserAPI.h> 


void bciFreeAttributes ( 


int objectCount, 
int attributeCount, 
void*** values); 
Parameters 
Par. Name: Direction: Description: 
objectCount in Number of objects 
attributeCount in Number of attributes 
values in/out Attribute data matrix pointer 
Description 


The bciFreeAttributes function deallocates the memory that was allocated with the 
bciAllocAttributes function. 


Return Value 


None. 


5.32.2 Example 


See for example Section 5.14, bciGetAttributes. 
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5.33 bciFreeOperations 


5.33.1 Description 


The purpose of this function is to deallocate operation argument array. 


Synopsis 
#include <bciUserAPI.h> 


void bciFreeOperations ( 


int objectCount, 
void** arguments) ; 
Parameters 
Par. Name: Direction: Description: 
objectCount in Number of objects 
arguments in/out Operation argument array pointer 
Description 


The bciFreeOperations function deallocates the memory that was allocated with the 
bciAllocOperations function. 


Return Value 


None. 


5.33.2 Example 


See for example Section 5.24, bciExecOperations. 
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5.34 bciFreeEvents 


5.34.1 Description 


The purpose of this function is to deallocate event data array. 


Synopsis 
#include <bciUserAPI.h> 


void bciFreeEvents ( 


int objectCount, 
void** eventData); 
Parameters 
Par. Name: Direction: Description: 
objectCount in Number of objects 
eventData in/out Event data array pointer 
Description 


The bciFreeEvents function deallocates the memory that was allocated with the bciAllocEvents 


function. 


Return Value 


None. 


5.34.2 Example 


See for example Section 5.18, bciGetAttributesOnEvent. 
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5.35 bciFreeObjectStatus 


5.35.1 Description 


The purpose of this function is to deallocate object status array. 


Synopsis 
#include <bciUserAPI.h> 


void bciFreeObjectStatus ( 


int objectCount, 
BciObjStatus** status); 
Parameters 
Par. Name: Direction: Description: 
objectCount in Number of objects 
Status in/out Object status array pointer 
Description 


The bciFreeObjectStatus function deallocates the memory that was allocated with the 
bciAllocObjectStatus function. 


Return Value 


None. 


5.35.2 Example 


See for example Section 5.14, bciGetAttributes. 
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5.36 bciFreeObjectTypeNames 


5.36.1 Description 


The purpose of this function is to deallocate object type name array. 


Synopsis 
#include <bciUserAPI.h> 


void bciFreeObjectTypeNames ( 


int objectCount, 
char** typeNames) ; 
Parameters 
Par. Name: Direction: Description: 
objectCount in Number of objects 
typeNames in/out Object type name array pointer 
Description 


The bciFreeObjectTypeNames function deallocates the memory that was allocated with the 
bciAllocObjectTypeNames function. 


Return Value 


None. 


5.36.2 Example 


See for example Section 5.7, bciDataTypeElements. 
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5.37 bciFreeObjectiDs 


5.37.1 Description 


The purpose of this function is to deallocate object ID array. 


Synopsis 
#include <bciUserAPI.h> 


void bciFreeObjectIDs ( 


int objectCount, 
BciOID** oid); 
Parameters 
Par. Name: Direction: Description: 
objectCount in Number of objects 
oid in/out Object ID array pointer 
Description 


The bciFreeObjectIDs function deallocates the memory that was allocated with the 
bciAllocObjectIDs function. 


Return Value 


None. 


5.37.2 Example 


See for example Section 5.8, bciGetObjectInformation. 
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5.38 bciSetQueueSize 


5.38.1 Description 


5.38.2 Example 
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This function sets the monitor queue for incoming packages from Advant OCS. 


Synopsis 
#include <bciUserAPI.h> 


BciStatus bciSetQueueSi ze ( 


int size); 
Parameters 
Par. Name: Direction: Description: 
size in New size of queue 
Description 


The beiSetQueueSize function sets the queue size of incoming packages from the Advant OCS. 
There is one queue for each attribute request and it is by default set to 20 packages per attribute. 
The queue size should only be redefined if your application temporarily do not manage to 
handle all data that arrives before the queue is full. (Access status flag code is set to 
bciOBJ_DATA_LOST) 


Return Value 


bciSUCCESS Successful completion 
bciLENGTH_REJECTED Not valid queue size 


/* Set size of attribute-queues to 50 packages */ 
result = beiSetQueueSize (50); 
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5.39 bciSetResolveTimeOut 


5.39.1 Description 


5.39.2 Example 
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This function sets the time out for resolving object instances. 


Synopsis 
#include <bciUserAPI.h> 


BciStatus bciSetResolveTimeOut ( 


double timeOut) ; 
Parameters 
Par. Name: Direction: Description: 
time Out in New time out in seconds 
Description 


The bciSetResolveTimeOut function sets the time out for resolving object instances in the 
Advant OCS. The default value is 30 seconds. 


Return Value 


bciSUCCESS Successful completion 
bciLENGTH_REJECTED Not valid time-out 


/* Set resolve time out to 60 seconds */ 
result = bciSetResolveTimeOut (60.0) ; 


5-73 


Advalnform® User API User’s Guide 
Chapter 5 Object Access Services 


5.40 bciSetWaitTimeOut 


5.40.1 Description 


This function sets the time out for waiting for demand data. 


Synopsis 
#include <bciUserAPI.h> 


BceiStatus bciSetWaitTimeOut ( 


double timeOut) ; 
Parameters 
Par. Name: Direction: Description: 
timeOut in New time out in seconds 
Description 


The bciSetWaitTimeOut function sets the time out for waiting for demand requests, for 
example bciGetAttributes. The default value is 60 seconds. 


Return Value 


bciSUCCESS Successful completion 
bciLENGTH_REJECTED Not valid time-out 


5.40.2 Example 


/* Set wait time out to 60 seconds */ 
result = bciSetWaitTimeOut (60.0); 
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5.41 bciGetConfiguration 


5.41.1 Description 


This function returns AdvaInform UserAPI configuration parameters. 


Synopsis 


#include <bciUserAPI.h> 


BciStatus bciGetConfiguration ( 


int* 
double* 
double* 


Parameters 


Par. Name: 
queueSize out 
resolveTimeOut out 


waitTime Out out 


Description 


Direction: 


queueSize, 
resolveTimeOut, 
waitTimeOut) ; 


Description: 
Size of queue 
Time out for resolving objects 


Time out for waiting for demand data 


The bciGetConfiguration function returns application configuration parameters. 


Return Value 


bciSUCCESS Successful completion 
5.41.2 Example 
int queueSize; 
double resolveTimeOut; 
double waitTimeOut; 


result = bciGetConfiguration (&queueSize, 


&resolveTimeOut, 
&waitTimeOut) ; 


printf (“Current configuration:\n”); 


printf (“Queue Size 


queueSize); 


printf (“Resolve Time-out 
printf (“Wait Time-out 


= $d packagaes/attribute-queue\n”, 


S— s\n”, resolveTimeOut) ; 
S— s\n”, waitTimeOut) ; 
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Chapter 6 Basic Support Services 


6.1 General 


The Basic Support Services is the 3-GL programming interface to the system resources. It 
covers, for example, handling of system messages and date and time. 


Each of the services in Table 6-1 are described in the following sections. All the examples listed 
are included in AdvaInform UserAPI. HP-UX path plus file name is written in the very first 
comment line of each example listing: 


/opt/advant /UserAPI/examples/file name 


In some cases a service has no example of its own. In those cases you are referred to an example 
of another service where the service at hand is used. 


The service(s) which is currently described is marked in boldface in the program listing. 


6.1.1 List of Basic Support Services 


Table 6-1. List of Basic Support Services 


Basic Support Services Summary Example Files 
bciGetLocalTime Convert the system time to local time. bciGetSystemTimeEx 
bciGetStandardTime Convert system time to UTC. bciGetSystemTimeEx 
bciGetSystemTime Get current system time. bciGetSystemTimeEx 
bciSetLocalTime Set current system time. bciSetLocalTimeEx 
bciGetMessageText Retrieve NLS message text. bciGetMessageTextEx 
bciFormatMessageText Format a NLS message text. bciSendMessageEx 
bciSendMessage Send a system message. bciSendMessageEx 
bciGetLocalNode Get local network and node. bciGetLocalNodeEx 
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6.2 bciGetLocalTime 


6.2.1 Description 


6.2.2 Example 


This function retrieves the local time and calendar date of the local node. 


Synopsis 


#include <bciUserAPI.h> 
#include <time.h> 


typedef struct bciTimeStamp 
{ 
time_t seconds; 
BcilInt32 microseconds; 
} BciTimeStamp; 


void bciGetLocalTime ( 


BciTimeStamp* systemTime, 
struct tm* localTime, 
BciInt32* microSeconds) ; 
Parameters 
Par. Name: Direction: Description: 
systemTime in Encoded system time 
localTime out Date and time components 
microSeconds out The microseconds component 
Description 


The bciGetLocalTime function is used to convert systemTime to local calendar time broken 
down into date and time components. The local time is the calendar time expressed for some 
specific time zone, and includes correction for Daylight Saving Time. 


The ANSI C format of the date and time components is used. This means that you can use the 
ANSI C function strftime for conversion to text format in a native language. 


Return Values 


None. 


See Section 6.4, bciGetSystemTime. 
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6.3 bciGetStandardTime 


6.3.1 Description 


6.3.2 Examples 


The function is used to convert the system time to standard (UTC-Universal Time Coordinated) 
calendar time broken down into date and time components. 


Synopsis 


#include <bciUserAPI.h> 
#include <time.h> 


typedef struct bciTimeStamp 
{ 


time_t seconds; 
BciInt32 microSeconds; 


} BciTimeStamp; 


void bciGetStandardTime ( 


BciTimeStamp* systemTime, 
struct tm* standardTime, 
BciInt32* microSeconds) ; 
Parameters 
Par. Name: Direction: Description: 
systemTime in Encoded system time 
standardTime out Date and time components 
microSeconds out The microseconds component 
Description 


The bciGetStandardTime function is used to convert systemTime to normalized calendar time 
broken down into date and time components. The normalized calendar time is global in the 
system, and does not include time zone correction. Universal Time Coordinated (UTC) is used. 


The ANSI C format of the date and time components is used. This means that you can use the 
ANSI C function strftime for conversion to text format in a native language. 


Return Values 


None. 


See Section 6.4, bciGetSystemTime. 


3BSE 011 011R0101 


Advalnform® User API User’s Guide 
Chapter 6 Basic Support Services 


6.4 bciGetSystemTime 


6.4.1 Description 


The function is used to get the current system time which is global in the system. 


Synopsis 
#include <bciUserAPI.h> 


typedef struct bciTimeStamp 
{ 


time_t seconds; 
BcilInt32 microSeconds; 
} BciTimeStamp; 


void bciGetSystemTime ( 


BciTimeStamp* systemTime) ; 
Parameters 
Par. Name: Direction: Description: 
systemTime out Encoded system time 
Description 


The bciGetSystemTime function is used to get the current system time as a time stamp value. 
The time stamp is global in the system, and does not include time zone correction. The time 
stamp can be broken down into date and time components using the services 
bciGetStandardTime and bciGetLocalTime. 


Return value 


None 


6.4.2 Example 


/* 
* /opt/advant/UserAPI/examples/bciGetSystemTimeEx.c 


* 


* Read system time. 


*/ 
#include <stdio.h> /* printf */ 
#include <time.h> /* struct tm */ 


#include <bciUserAPI.h> /* UserAPI include file */ 
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void main () 


{ 


BciTimeStamp systemTimeStamp; 
struct tm time; 
BceilInt32 microSec; 


#ifdef __hpux 


_main(); /* Run constructor for C++ as program coded in C */ 


#endif 


6.5 bciSetLocalTime 


6.5.1 Description 


/* Get system time stamp */ 
bciGetSystemTime (&systemTimeStamp) ; 


/* Convert system time to standard (utc) time */ 

bciGetStandardTime (&systemTimeStamp, &time, &microSec); 

printf (“UTC:\t%02d-%02d-%02d %02d:%02d:%02d.%061d\n"”, 
time.tm_mon + 1, time.tm_mday, time.tm_year, 
time.tm_hour, time.tm_min, time.tm_sec, microSec); 


/* Convert system time to local time */ 

bciGetLocalTime(é&systemTimeStamp, &time, &microSec); 

printf (“LOCAL: \t%02d-%02d-%02d %02d:%02d:%02d.%061d\n", 
time.tm_mon + 1, time.tm_mday, time.tm_year, 
time.tm_hour, time.tm_min, time.tm_sec, microSec); 


This function sets the local time and calendar date of the local node. 


Synopsis 


#include <bciUserAPI.h> 
#include <time.h> 


BeiStatus bciSetLocalTime ( 


const struct tm* localTime, 
BciInt32 microSeconds) ; 
Parameters 
Par. Name: Direction: Description: 
localTime in Date and time components 
microSeconds in The microseconds component 
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6.5.2 Example 
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Description 


The bciSetLocalTime function is used to set the system time, expressed as the local calendar 
time broken down into date and time components. The local time is valid for the time zone, and 
includes correction for Daylight Saving Time. The user must at least be a SYSTEM category 
user and the IMS node must be configured to be clock-master. 


The ANSI C format of the date and time components is used. This means that you can use the 
ANSI C function strftime for conversion to text format in a native language. 


NOTE 


Read in the Advant Station 500 IMS User’s Guide about Time Synchronization. 
The IMS node must be properly configured for the time synchronization to 
function. You must also be aware of the consequences for other AdvaInform 
functions if the time is set wrong or improperly. 


Return Values 


bciSUCCESS Successful completion 
bciNOT_EXISTING No such user exists 
bciNO_PRIVILEGE Privilege not allowed 
bciNOT_FOUND Clock synchronization object not found 
bciABORT Node not configured to clock master 

y: * 


* /opt/advant/UserAPI/examples/bciSetLocalTimeEx.c 
* 


* Set system time. 


a 
#include <stdio.h> /* printf */ 
#include <time.h> /* struct tm */ 


#include <bciUserAPI.h> /* UserAPI include file */ 


void main() 


{ 


struct tm time; 
BcilInt32 microSec; 
BciStatus result; 


#ifdef __hpux 
_main(); /* Run constructor for C++ as program coded in C */ 
#endif 


/* Setting local time 3-26-1996 15:30:00:0000 */ 


time.tm_year = 96; /* Year = 1996 */ 
time.tm_mon = 3; /* Month = April */ 
time.tm_mday = 26; /* Day = 26 */ 
time.tm_hour = 15; /* Hour = 15 */ 
time.tm_min = 30; /* Minutes = 30 xf 
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6.6 bciGetMessageText 


6.6.1 Description 


time.tm_sec = 0; /* Seconds = 0 */ 
time.tm_isdst = 1; /* Daylight = yes */ 
microSec = 0; /* Microseconds = 0 Hf 
result = beiSetLocalTime (&time, microSec) ; 
if (result != bciSUCCESS) 
{ 
printf (“bciSetLocalTime() ERROR %d\n”, result); 
} 
} 
This function retrieves NLS message texts to the application. 
Synopsis 
#include <bciUserAPI.h> 
const char* bciGetMessageText ( 
int component, 
int messageNumber) ; 
Parameters 
Par. Name: Direction: Description: 
component in Number of the user application 
messageNumber in Number of the message text 
Description 


The bciGetMessageText function is used to retrieve NLS message texts. 


The component and messageNumber identify the message text that is picked up from the 
message file. The message text is returned through the function return parameter. 


Return value 


The message text retrieved. 
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6.6.2 Example 


/* 
* /opt/advant/UserAPI/examples/bciGetMessageTextEx.c 


*x 


* Translate component, message number to NLS text. 


*/ 

#include <stdio.h> /* printf */ 

#include <bciUserAPI.h> /* UserAPI include file */ 
#include <bsBCI_def.h> /* NLS component constants */ 


/* Offset that is used to get correct translation of status codes to 
text */ 
static const int Offset = 128; 


void main() 


{ 


const char* statusText; 
int component = FuncStatus; 
BciStatus result = bciSUCCESS; 


#ifdef _ hpux 
_main(); /* Run constructor for C++ as program coded in C */ 
#endif 


/* Return status from any UserAPI function can be translated to text 
result = bciFunction(); 


Ae 


/* Get message text */ 

statusText = bciGetMessageText (component, Offsett+result); 
printf (“Function returns: %s\n”, statusText); 

} 
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6.7 bciFormatMessageText 


6.7.1 Description 
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This function formats a NLS message text with parameters. 


Synopsis 
#include <bciUserAPI.h> 


char* bciFormatMessageText ( 


const char* message, 
int datal, 
int data2, 
const char* textData, 
char* buffer, 
int bufferLength) ; 
Parameters 
Par. Name: Direction: Description: 
message in Message text received from bciGetMessageText 
datal in Application data nr | 
data2 in Application data nr 2 
textData in Application text data 
bufferLength in Size of text buffer 
buffer in/out Formatted message text string 
Description 


The bciFormatMessageText function formats the message text received from the 
bciGetMessageText function call. It inserts the data and text arguments in the string as specified 
in the message argument, and updates the buffer. The formatted message text is also returned 
from the function. 


The message argument is the unformatted message text retrieved. 
The datal, data2 and textData arguments are inserted as values into the formatted text. 
The buffer argument is the returned formatted text buffer. 


The bufferLength argument is the length of the buffer supplied by the application. 


Return value 


Formatted message text string 
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6.7.2 Example 


See Section 6.8, bciSendMessage. 


6.8 bciSendMessage 


6.8.1 Description 


The purpose of this function is to send error messages to the System Message Log. 


Synopsis 
#include <bciUserAPI.h> 


typedef enum BciSeverity 
{ 
bciINFROMATION, 
bciWARNING, 
bciERROR, 
bciFATAL 
} BciSeverity; 


typedef enum BciAudience 
{ 
bciOPERATOR, 
bciENGINEER, 
bciSERVICE, 
bciDEBUG 
} BciAudience; 


void bciSendMessage ( 


int component, 
int messageNumber, 
const char* objectName, 
const char* fileName, 
int lineNumber, 
BciSeverity severity, 
BciAudience audience, 
int datal, 
int data2, 
const char* textData) ; 
Parameters 
Par. Name: Direction: Description: 
component in Number of the user application 
messageNumber in Number of the message text 
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objectName in Name of the object/application generating the message 
fileName in Name of the program file 

lineNumber in Line number in the program file 

severity in Level of the error 

audience in Intended audience of the message 

datal in Application data 

data2 in Application data 

textData in Application data 

Description 


The bciSendMessage function is used to send a message to the System Message Log. 


The component and messageNumber identify the message text that is picked up from the 
message file. 


The fileName and lineNumber (should) identify where in your code the message is generated. 


The severity argument indicates whether the message reports a Fatal condition (which renders a 
node or a major subsystem unusable), an Error condition (which causes failure of an individual 
action but does not affect subsequent actions), a Warning (which reports a potential problem), or 
Information (either a recovery from an error condition, a successful conclusion to an activity 
which cannot be reported to the user any other way, or any other indication to the user which 
does not require any response). 


The audience argument indicates to what level of user the message is intended for. 


The extra data arguments give you possibility to supply more information about the cause of the 
message. 


Return value 


None. 
6.8.2 Example 
/* 
* /opt/advant/UserAPI/examples/bciSendMessageEx.c 
* 
* Sends system message log. 
ca 
#include <stdio.h> /* printf */ 
#include <bciUserAPI.h> /* UserAPI include file */ 
#include <bsBCI_def.h> /* NLS component constants */ 


#include <userl_bsBCI_def.h> /* NLS message constants */ 


void main () 
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{ 


const char* message; 

int component = Userl; 

int messageNumber = Message6_Userl_bsBCI; 
char* objName = “UserAPI Example”; 
BciSeverity severity = bciINFORMATION; 
BciAudience audience = bciOPERATOR; 

int datal = 1; 

int data2 = 2; 

char* textData = “Text Data”; 

char buffer[20]; 


#ifdef __hpux 
_main(); /* Run constructor for C++ as program coded in C */ 
#endif 


/* Get message text */ 
message = bciGetMessageText (component, messageNumber) ; 
printf(“NLS message : %s\n”, message); 


/* Format message text */ 
message = bciFormatMessageText (message, datal, data2, textData, 
buffer, sizeof (buffer) ); 
printf(“This message will be sent to System Messages : %s\n”, 
message); 


/* Send message to bslog, System Messages */ 
printf (“Sending message to System Messages...\n"”); 
bciSendMessage (component, messageNumber, ob jName, 
FILE, LINE, 
severity, audience, datal, data2, textData); 
/* Note that the text format is not necessary if you only want to send 
a message to System Messages, not print it out. */ 
} 
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6.9 bciGetLocalNode 


6.9.1 Description 
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The function is used to retrieve the network and node number of the local node. 


Synopsis 
#include <bciUserAPI.h> 


void bciGetLocalNode ( 


unsigned int* localNetwork, 
unsigned int* localNode) ; 
Parameters 
Par. Name: Direction: Description: 
localNetwork out Number of the local network 
localNode out Number of the local node 


(DCN sub-device address) 


Description 
The bciGetLocalNode function is used to retrieve the network and node number of the local 


node. 


Return value 


None 
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6.9.2 Example 
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/* 
* /opt/advant/UserAPI/examples/bciGet LocalNodeEx.c 


* 


* Retrieve network and node number. 


a4 


#include <stdio.h> /* printf */ 
#include <bciUserAPI.h> /* UserAPI include file */ 


void main() 
{ 
unsigned int node; 
unsigned int network; 


#ifdef __hpux 


_main(); /* Run constructor for C++ as program coded in C */ 


fendif 


bciGetLocalNode(é&network, &node); 
/* Note: Node is always 0 for MOD 300 IMS stations 
printf (“Network = %$d, Node = %d\n”, network, node); 


} 


ef. 
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FAQ consists of questions often put to ABB Industrial Systems support centers. For each new 
release/revision of this guide the list will be updated. 


These are the most common questions received so far: 


1. 
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When should I use cyclic and/or event-based functions. When should I use 
demand-based functions? 


Use a cyclic function when large amounts of data are read at a 1 second interval. Use 
demand functions, combined with the so called Do Request functions, in other cases where 
you do not read the data just once. 


Use event functions when data is to be read due to an event, such as a value change (Master 
only). 


When is it better to use bciGetAttribute instead of bciDoRequest? 


bciGetAttributes is only recommended for single, not repeated, demands. Use 
bciDoRequest when you read from an object more than twice. This improves performance 
and lowers the CPU load. 


Do not use bciDoRequest for write as you can not change the operation parameters 
between each execution. 


Why is it not possible to change some attributes of the AdvaInform Basic Object 
(AI,AO...) types (Master)? 


The AdvalInform Basic Objects are designed according to the corresponding Advant 
Controller objects. Process Station objects do not allow you to modify some of the 
attributes and the AdvaInform Basic Objects work the same way. If you want to modify a 
specific attribute, you have to create your own object type with AdvaBuild Object Type 
Builder. Inherit the object type you want to modify. After that you have to add an operation 
that supports update of the attribute. 


Why is it not possible to modify a History log entry? 


You can modify a History log entry. However, in order to do so you have to define the time 
stamp of the existing log entry, including the microSeconds. 


Can I use the UserAPI in C++ applications in HP-UX? 


Yes, you can use the C++ make file 
/opt/advant/UserAPI/examples/apiMakefile.Cc. 


Edit the file and set APIPROG to the name of your application. Then enter: 
S$ make -f apiMakefile.Cc 
If you are using Windows NT, simply add the file extension, CC, to apiMake.bat: 


> apiMake application CC 
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7.1 Do’s and Do Not’s 
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The following are recommendations on what you should and should not do to achieve, for 
example, best performance: 


Do use the DoRequest functionality as much as possible. 
It makes your programming easier and improves performance in most cases. 


Do start from the examples provided (see Chapter 5, Object Access Services and Chapter 
6, Basic Support Services) 


That will help you to start at a higher level. 
Do Not ask for object attributes from one object at a time, one attribute at a time. 


Ask for all the attributes you want from an object in one request. If you need the same 
attribute(s) from several objects, read them from all objects in one request. 


The more objects/attributes you include in one request the better the performance will be. 
If possible, use bciDoRequest to collect a number of small requests into one large 


Do Not send one request for an execute operation at a time. 


Try to include as many requests to that kind of object type as possible into one call of 
bciExecOperations. 


Do Not fork a process and execute UserAPI calls from both parent and child at the same 
time. Your application will behave unpredictably due to process inheritance (shared 
memory, file descriptors and so on). 
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There are two types of status codes in the UserAPI. 


2 Function return status 


Returned by function calls and reflects only the status of the function call itself, for 


example illegal arguments. 


° Object access status 


Status of each object that is accessed. Consists of flags and status codes. The flags are used 
to report information that can coexist with the status code, for example if the attribute 
value has changed since last read. (Should not be mixed up with the STATUS attribute of 


an object) 


All function return- and object-status codes are defined in the bciUserAPI.h header file. 


A.2 Return Status Codes 
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Table 1-1. Return Status Codes 


Name Code Description 
bciFIRST_ERROR -128 First code that marks error 
bciNOT_SUPPORTED -127 API internal 
bciTIMEOUT -126 |Communication service time-out 
bciVERSION -125 API internal 
bciALLOCATION -124 | Could not allocate resource 
bciREFERENCE -123 | Illegal unique identity 
beiILLEGAL_NAME -122  |A specified symbol uses illegal characters 
bciILLEGAL_MONITOR -121 API internal 
bciILLEGAL_UAC -120 | Illegal UAC in UAF 
bciINCONSISTENCY -119 | API internal 
bciALREADY_DEFINED -118 API internal 
bciIN_USE -117 Busy in access service or association 
bciT YPE -116 | Illegal object type name 
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Table 1-1. Return Status Codes (Continued) 


Name Code Description 
bciNO_RESOURCE -115 API internal 
bciNO_S YNCH -114 API internal 
bciS YNTAX_ERROR -113 API internal 
bciNO_PRIVILEGE -112 Privilege not allowed 
bciLENGTH_REJECTED -111 Unable to create wanted queue size 
bciWRONG_NODE -110 API internal 
bciWRONG_DOMAIN -109 |API internal 
bciMOVED -108 | Name Server error: Object moved 
bciRENAMED -107 | Name Server error: Object removed 
bciNOT_FOUND -106 | Name Server error: Object not found 
bciABORT -105 | Server aborted object request 
bciFAILURE -104 | Object or its methods failed 
bciINACTIVE -103 | Server object not active 
bciNOT_IMPLEMENTED -102 | Objects service or method not implemented 
bciMISSING -101 | Not all methods are supplied 
bciNO_MATCHING_CAP -100 | All capabilities are errenous or pending 
bciCAP_IN_USE -99 API internal 
bciNO_ASSOCIATION -98 No subscription exists 
bciFOUND_OUTSIDE_SCOPE -97 API internal 
bciALREAD Y_REGISTERED -96 API internal 
bciNO_TRANSLATION -95 Could not translate name to identifier 
bciNOT_DEFINED -94 API internal 
bciARRAY_BOUNDS -93 Max_is is lesser than last_is in open array 
bciNOT_EXISTING -92 No such user exists 
bciNOT_OPEN -91 OMEF could not be opened 
bciCOMM_FAIL -90 Communication failure 
bciNAME -89 Name Server error: Object type OK, Name 

error 

bciALREADY_IN_TYPED_VIEW -88 API internal 
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Table 1-1. Return Status Codes (Continued) 


Name Code Description 
bciENTRY_DELETED -87 API internal 
bciMONITOR_IN_USE -86 API internal 
bciNO_SERVICE -85 API internal 
bciERRONEOUS_CAPS -84 One or more capabilities are errenous 
bciAPI_FIRST_ERROR -20 First User API specific error code 
bciAPI_RESOURCE_LACK -18 Lack of resources (memory) 
bciAPI_EXE FAILED -17 Operation could not be executed 
bciAPI_ERR_EVSIZE -16 Error in eventSize specification 
bciAPI_ERR_OPSIZE -15 Error in operSize specification 
bciAPI_ERR_VALSIZE -14 Error in valueSize specification 
bciAPI_ERR_ EVENT -13 Error in event specification 
bciAPI_ERR_ OPER -12 Error in operation specification 
bciAPL ERR ATTRIB -11 Error in attribute specification 
bciAPI_ERR_ TIMEOUT -10 Time out value out of range 
bciAPI_LAST_ERROR -1 Last User API specific error code 
bciLAST_ERROR -1 Last code that marks an error 
bciPENDING 0 Complete service result not available 
bciFIRST_SUCCESS 1 First code that marks success 
bciSUCCESS 1 Service was successfully completed 
bciMORE 2 More events/data queued 
bciEMPTY 3 No more waiting events/data 
bciNO_SPACE 4 Not enough space in receiving array 
bciUNRESOLVED 5 View is unresolved 
bciALREADY_OPEN 6 OME already opened 
bciINTERRUPT y System call made by OMF was interrupted 
bciSERVER_RESTARTED 8 An OME server node has restarted 
bciLAST_SUCCESS 127 Last code that marks success 
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A.3.1 Object Status Codes 
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Table 1-2. Object Status Codes 


Name Code Description 
bciCAP_INCONSISTENCY -120 | Capability is not in a consistent state 
bciCAP_ARRAY_ BOUNDS -119 | Mismatch in open array bounds 
bciCAP_UNION_TAG -118 Invalid tag or union 
bciOBJ_NOT_RESOLVED -117 Object could not be resolved 
bciOBJ_UNREGISTERED -116 | Object not registered 
bciOBJ_OBJECT_MOVED -115 Object moved 
bciOBJ_-NODE_DOWN -114 | Object’s node not reachable 
bciOBJ_NODE_UP -113 Object’s node now reachable again 
bciOBJ_LREQUEST_TIMEOUT -112  |Communication time-out 
bciOBJ_TIMEOUT -111 Cyclic time-out 
bciOBJ_COMM_ FAIL -110 |Communication failure 
bciOBJ_RESTARTED -109 |OMF has restarted 
bciOBJ_PENDING -108 Communication failure 
bciOBJ_PING_TIMEOUT -107 Ping request has timed out 
bciOBJ_FAILURE -64 Generic method failure 
bciOBJ_PARAMETER -63 Parameter error in operation 
bciOBJ_ PERMISSION -62 User not permitted to access element 
bciOBJ_STATUS 1 - -61- | Customized object status. Dependent on the 
bciOBJ_STATUS32 -30 specific object server!) 
bciOBJ_SUCCESS 1 Successful access of object 
bciOBJ_LAST 127 Last status code 


(1) See Advalnform Object Types Reference Manual 
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Table 1-3. Flag Codes 


Name Code Description 
bciOBJ_NO_FLAG 0 No flag value 
bciOBJ_CHANGED 1 Value changed since last get 
bciOBJ_DATA_LOST 2 Data lost after this value 
bciOBJ_REFRESHED 4 Value is new due to refresh 
bciOBJ_SUSPENDED 8 Object association has been suspended 
bciOBJ_EXTENDED 16 Value due to extended association 
bciOBJ_REDUCED 32 Association has been removed 
bciOBJ_TERMINATED 64 Object association has been terminated 
bciOBJ_LRENAMED 128 Object has been renamed 
bciOBJ_SERVER_BUSY 256 | Object request in use by server 
bciOBJ_SERVER_PENDING 512 Object data might not be consistent 


A.4.1 Table of Text Indexes 


Table 1-4 describes all text indexes. In Section A.4.2, Translation of Text Index, you can learn 
how to translate from index to text. 
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Table 1-4. Table of Text Indexes 


Name Code Description 
TXT_IND_MSG_1 1 Invalid operation code 
TXT_IND_MSG_2 2 Invalid operation property 
TXT_IND_MSG_3 3 Object not implemented (or not selected) 
TXT_IND_MSG_4 4 Operation is not allowed when process update is 
TXT_IND_MSG_5 5 Limit out of range - input ignored 
TXT_IND_MSG_6 6 Value out of range - input ignored 
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Name Code Description 
TXT_IND_MSG_7 7 Limit not used - input ignored 
TXT_IND_MSG_8 8 Manual orders blocked - order ignored 
TXT_IND_MSG_9 9 Blocking of integration not allowed - order ignored 
TXT_IND_MSG_10 10 Blocking of integration not allowed - order 

ignored 
TXT_IND_MSG_11 11 Manual mode selection not allowed 
TXT_IND_MSG_12 12 Auto mode selection not allowed 
TXT_IND_MSG_13 13 El mode selection not allowed 
TXT_IND_MSG_14 14 E2 mode selection not allowed 
TXT_IND_MSG_15 15 E3 mode selection not allowed 
TXT_IND_MSG_16 16 Setpoint is tracking 
TXT_IND_MSG_17 17 Output value can only be changed in manual mode 
TXT_IND_MSG_18 18 Output value is connected to external reference 
TXT_IND_MSG_19 19 Three point control not implemented - DZ not use 
TXT_IND_MSG_20 20 M1 main order blocked - order ignored 
TXT_IND_MSG_21 21 MO main order blocked - order ignored 
TXT_IND_MSG_22 22 MO spare order blocked - order ignored 
TXT_IND_MSG_23 23 M1 spare order blocked - order ignored 
TXT_IND_MSG_24 24 Object not selected - order ignored 
TXT_IND_MSG_25 25 DCM-communication failure - order ignored 
TXT_IND_MSG_26 26 Order not allowed for distributed 
TXT_IND_MSG_27 27 Output blocked - order ignored 
TXT_IND_MSG_28 28 Order not allowed in this mode - order ignored 
TXT_IND_MSG_29 29 Object already blocked 
TXT_IND_MSG_30 30 Object not blocked 
TXT_IND_MSG_31 31 Object already in manual mode 
TXT_IND_MSG_32 32 Object already in auto mode 
TXT_IND_MSG_33 33 Board already in service 
TXT_IND_MSG_34 34 Board already out of service 
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Table 1-4. Table of Text Indexes (Continued) 


Name Code Description 
TXT_IND_MSG_35 35 No instances connected to board 
TXT_IND_MSG_36 36 Ratio connected to external reference 
TXT_IND_MSG_37 37 Main open order blocked - order ignored 
TXT_IND_MSG_38 38 Main close order blocked - order ignored 
TXT_IND_MSG_39 39 Main stop order blocked - order ignored 
TXT_IND_MSG_40 40 Increase small step blocked - order ignored 
TXT_IND_MSG_41 41 Increase large step blocked - order ignored 
TXT_IND_MSG_42 42 Decrease small step blocked - order ignored 
TXT_IND_MSG_43 43 Decrease large step blocked - order ignored 
TXT_IND_MSG_44 44 Spare open order blocked - order ignored 
TXT_IND_MSG_45 45 Spare close order blocked - order ignored 
TXT_IND_MSG_46 46 Spare stop order blocked - order ignored 
TXT_IND_MSG_47 47 Object already in hold mode 
TXT_IND_MSG_48 48 Object not implemented 
TXT_IND_MSG_49 49 Step conditions not fulfilled 
TXT_IND_MSG_50 50 Input blocked - status check not performed 
TXT_IND_MSG_51 51 Instance does not exist or board not implemented 
TXT_IND_MSG_52 52 Board out of service 
TXT_IND_MSG_53 53 Hardware error reported 
TXT_IND_MSG_54 54 Output temporary locked - try again 
TXT_IND_MSG_55 55 Output failed 
TXT_IND_MSG_56 56 Attempt to read input failed 
TXT_IND_MSG_57 57 Illegal data type - call for system manager 
TXT_IND_MSG_58 58 Concept/property not found in LF 1 - call for SY 
TXT_IND_MSG_59 59 The sequence is not running - order ignored 
TXT_IND_MSG_60 60 Event print already blocked 
TXT_IND_MSG_61 61 Event print already deblocked 
TXT_IND_MSG_62 62 Event proc. already blocked. 
TXT_IND_MSG_63 63 Event proc. already deblocked 
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Name Code Description 
TXT_IND_MSG_64 64 Limit is not active for this object 
TXT_IND_MSG_65 65 The input is not calculated - order ignored 
TXT_IND_MSG_66 66 Attempt to change max limit to be less than min 
TXT_IND_MSG_67 67 Attempt to change min limit to be greater than max 
TXT_IND_MSG_68 68 Flag in mord allowed is not true - order ignored 
TXT_IND_MSG_69 69 Flag in value allowed is not true - order ignored 
TXT_IND_MSG_70 70 Object is selected by an another operator - order 

ignored 
TXT_IND_MSG_71 71 Value out of range 
TXT_IND_MSG_72 72 Attempt to change OP_MAX to be < OP_MIN 
TXT_IND_MSG_73 73 Attempt to change OP_MIN to be > OP_MAX 
TXT_IND_MSG_74 74 Attempt to change SP_MAX to be < SP_MIN or 
OUT O 
TXT_IND_MSG_75 75 Attempt to change SP_MIN to be > SP_MAX or 
out o 


A.4.2 Translation of Text Index 
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Use the bciGetMessageText function to translate text index code to text. Select the correct 
component from bsBCI_def.h and decrease the trext index code with the dcxbt xt_offset 
constant (defined in dccodes.hh). For example: 


#include <bciUserAPI.h> 
#include <bsBCI_def.h> 
#include <dccodes.hh> 


printf (“Operation status = %d (%s)”, 
textIndex, 
bciGetMessageText (OpStatus, textIndex-dcxbtxt_offset) 
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